diff --git a/docs/config.json b/docs/config.json index 1ac45154a1522..2e5d6e98b5b9e 100644 --- a/docs/config.json +++ b/docs/config.json @@ -660,6 +660,10 @@ "title": "Using Teleport Connect", "slug": "/connect-your-client/teleport-connect/" }, + { + "title": "Using PuTTY", + "slug": "/connect-your-client/putty/" + }, { "title": "Database GUI Clients", "slug": "/connect-your-client/gui-clients/" diff --git a/docs/cspell.json b/docs/cspell.json index 51b3b6398e788..1d735bf4a6867 100644 --- a/docs/cspell.json +++ b/docs/cspell.json @@ -73,6 +73,7 @@ "Goland", "Grafana's", "Gtczk", + "HKEY", "HSTS", "Hqlo", "IAMR", @@ -106,6 +107,7 @@ "MAINPID", "MDAs", "MGET", + "Moba", "MYDNS", "MYELB", "MYIP", @@ -173,6 +175,7 @@ "Svhk", "Swic", "Swicm", + "Tatham", "TCPS", "TELEPORTING", "TENANTID", @@ -211,6 +214,7 @@ "Zrpsaln", "abcdefghijklm", "aclfile", + "acmecorp", "acpi", "actionstest", "adcli", @@ -308,6 +312,7 @@ "codingllama", "compat", "compinit", + "compu", "cond", "configmap", "connectorname", @@ -617,6 +622,7 @@ "pstree", "ptgott", "ptrace", + "puttyconfig", "pwgen", "quicktime", "rabbitmq", @@ -632,6 +638,7 @@ "reauthentication", "rediscluster", "redisinsight", + "reco", "rediss", "regexes", "relogged", diff --git a/docs/img/connect-your-client/putty-console.png b/docs/img/connect-your-client/putty-console.png new file mode 100644 index 0000000000000..ff83d635004cf Binary files /dev/null and b/docs/img/connect-your-client/putty-console.png differ diff --git a/docs/img/connect-your-client/putty-window.png b/docs/img/connect-your-client/putty-window.png new file mode 100644 index 0000000000000..39899857ecad9 Binary files /dev/null and b/docs/img/connect-your-client/putty-window.png differ diff --git a/docs/pages/connect-your-client/putty.mdx b/docs/pages/connect-your-client/putty.mdx new file mode 100644 index 0000000000000..099d1f6e3b1aa --- /dev/null +++ b/docs/pages/connect-your-client/putty.mdx @@ -0,0 +1,247 @@ +--- +title: Using PuTTY to connect to SSH nodes via Teleport +description: This reference shows you how to use PuTTY to connect to SSH nodes through Teleport +--- + +This guide will show you how to use the Teleport client tool `tsh` to add saved sessions for use +with [PuTTY](https://www.putty.org/), and then how to use PuTTY as a client to connect to SSH nodes. + +You will learn how to: + +- Generate saved PuTTY sessions for SSH nodes attached to a Teleport cluster. +- Log in to an interactive shell using these saved PuTTY sessions. + + +## Prerequisites + +- A client machine running Windows 10 or higher. You can only use `tsh` to save PuTTY sessions on Windows. + +- The Teleport `tsh.exe` client, version 14.0.0 or higher. To download the `tsh.exe` client, run the following command: + + ```code + $ curl.exe -O https://cdn.teleport.dev/teleport-v(=teleport.version=)-windows-amd64-bin.zip + ``` + + You should then unzip the archive and move `tsh.exe` to your `%PATH%`. + +- PuTTY for Windows version 0.78 or higher. You can download the latest version of PuTTY from the [PuTTY download page](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html). + + +## Summary + +To add saved sessions to PuTTY: + + + +1. Sign into a Teleport cluster using the `tsh login` command: + +```bash +C:\Users\gus>tsh login --proxy=teleport.example.com +``` + +This command retrieves your user certificates and saves them in a local file in the `%USERPROFILE%/.tsh` directory. + +2. List SSH nodes that the user can connect to inside the cluster: + +```bash +C:\Users\gus>tsh ls +Node Name Address Labels +----------------------------------- -------------- ---------------------------- +ip-172-31-30-140 127.0.0.1:3022 company=acmecorp,env=aws,... +ip-172-31-34-128.us-east-2.compu... ⟵ Tunnel access=open,enhanced_reco... +``` + +3. Add a saved session for a specific login on a specific node to the Windows registry. + +For example, you can add a saved session for the login `ubuntu` on the node `ip-172-31-30-140` to the Windows +registry by running the following command: + +```bash +C:\Users\gus>tsh puttyconfig ubuntu@ip-172-31-30-140 +Added PuTTY session for ubuntu@ip-172-31-30-140 [proxy:teleport.example.com] +``` + +If you don't provide a login to this command, your local Windows username is used instead. + + + + +1. Sign into a Teleport cluster using the `tsh login` command: + +```bash +C:\Users\gus>tsh login --proxy=mytenant.teleport.sh +``` + +This command retrieves your user certificates and saves them in a local file in the `%USERPROFILE%/.tsh` directory. + +2. List SSH nodes that the user can connect to inside the cluster: + +``` +C:\Users\gus>tsh ls +Node Name Address Labels +----------------------------------- -------------- ---------------------------- +ip-172-31-30-140 ⟵ Tunnel company=acmecorp,env=aws,... +ip-172-31-34-128.us-east-2.compu... ⟵ Tunnel access=open,enhanced_reco... +``` + +3. Add a saved session for a specific login on a specific node to the Windows registry. + +For example, you can add a saved session for the login `ubuntu` on the node `ip-172-31-30-140` to the Windows +registry by running the following command: + +```bash +C:\Users\gus>tsh puttyconfig ubuntu@ip-172-31-30-140 +Added PuTTY session for ubuntu@ip-172-31-30-140 [proxy:mytenant.teleport.sh] +``` + +If you don't provide a login to this command, your local Windows username is used instead. + + + + +## Use a saved session to connect with PuTTY + +1. Start PuTTY to see the saved sessions available for your cluster. + +
+![Main PuTTY window](../../img/connect-your-client/putty-window.png) +
+ +2. Double-click a session to connect to the host through Teleport. + +
+![PuTTY console](../../img/connect-your-client/putty-console.png) +
+ +After you connect to the host, Teleport generates an audit log entry for the session's start, +and appears in the list of "Active Sessions" within Teleport. + +You can run `teleport status` inside the session to verify that it is connected through +the Teleport proxy and to output the session's UUID for tracking purposes. +If session recording is enabled for your cluster, you can also view a +recording of the session after you stop the session and disconnect from the host.. + + +## Leaf clusters + +To list available leaf clusters, run the following command: + +```bash +C:\Users\gus>tsh clusters +Cluster Name Status Cluster Type Labels Selected +----------------- ------ ------------ ------ -------- +teleport.example.com online root * +example.teleport.sh online leaf +``` + +You can access a leaf cluster in a PuTTY session by adding the `--leaf ` parameter to the `tsh puttyconfig` command. + +For example, if your leaf cluster is named `example.teleport.sh` and your node is called `ip-172-31-34-128.us-east-2.compute.internal`, +you can add a PuTTY session for the login `ec2-user` using the following command: + +```bash +C:\Users\gus>tsh puttyconfig --leaf example.teleport.sh ec2-user@ip-172-31-34-128.us-east-2.compute.internal +Added PuTTY session for ec2-user@ip-172-31-34-128.us-east-2.compute.internal [leaf:webby.teleport.sh,proxy:teleport.example.com] +``` + + +## Session naming + +Sessions are named using the following schema: + +Root clusters: `@ [proxy:]` + +Leaf clusters: `@ [leaf:,proxy:]` + +## Frequently asked questions + +### Do I need administrator rights on my machine to run `tsh puttyconfig`? + +No, `tsh` only makes changes to the `HKEY_CURRENT_USER` registry key. + +### Can I add saved PuTTY sessions for all users on a machine? + +No, sessions are only added for the current user. You can export the sessions for another user to import using the +registry export method described below. + +### Can I export my saved PuTTY sessions to another machine? + +Yes, use the Registry Editor to export the `HKEY_CURRENT_USER\Software\SimonTatham\PuTTY` registry key to a file +and import this file on another machine. Note that you will need admin rights to run Registry Editor. + +### Can I change the font size, window size, or other preference for my saved PuTTY sessions? + +After a session has been added, you can make changes to it in the PuTTY UI by clicking the session name in the +"Saved sessions" list, then clicking **Load**. Make all the necessary changes, then choose the session again and click **Save**. + +### If I re-run `tsh puttyconfig` for a given host, will it overwrite any custom changes I've made to the saved session? + +Teleport only modifies the configuration parameters that it relies on, like the proxy name, proxy command, hostname, username, and so on. +Any changes to font size, window size, and other parameters are left untouched. + +### Can I use other graphical clients like MobaXterm or SecureCRT? + +Only PuTTY support is implemented at present. Most other graphical clients do not fully support the use of both SSH user +certificates and SSH host certificates for authentication which is a requirement to use Teleport. + +Please contact the authors of those clients if you wish to see support for Teleport sessions added. + +### Can I use forks of PuTTY like KiTTY or Solar PuTTY? + +If the fork uses PuTTY 0.78 or higher as its base, it may work. However, the Teleport team only tests stock versions of PuTTY +and cannot provide support for forked versions. + +### Can I use my saved Teleport PuTTY sessions with WinSCP? + +At the time of writing, WinSCP doesn't support validation using host certificates. Because Teleport requires host +certificate validation, you can't yet use WinSCP to connect to a host through Teleport. + +You can track the status of this feature request and vote for it on the WinSCP bug tracker: https://winscp.net/tracker/2145 + +### Can I use an alternative Teleport authentication method (`tsh login --auth`) with saved sessions? + +No, PuTTY calls `tsh proxy ssh` which uses the default authentication method configured for the Teleport cluster. + +For more information about Teleport authentication, see [Authentication options](../reference/authentication.mdx). + +Advanced users can use the Registry Editor to modify the PuTTY proxy command themselves under the `ProxyTelnetCommand` +key. Note that if you re-run `tsh puttyconfig` for the given hostname, this command is overwritten. + + +## Troubleshooting + +### `proxy: ERROR: access denied to connecting to ` + +You have provided an incorrect login username to the `tsh puttyconfig` command. Re-run the command with a login username +that your Teleport user/role has permissions to use. Check the logins listed under the `logins` role specification or user trait. + +If you can log in successfully with `tsh ssh`, you should be able to use the name login/hostname with `tsh puttyconfig`. + +### `proxy: ERROR: ssh: subsystem request failed` + +The Teleport proxy is unable to connect to the given host/port provided in the saved session. This may mean that the node is +offline. Check that the node is visible in `tsh ls` and that you can connect to it with `tsh ssh login@hostname`. If this is +successful, check the Teleport proxy logs for more detailed errors. + +### `Unable to use certificate file "C:\Users\\.tsh\keys\\-ssh\-cert.pub" (unable to open file)` + +You are not logged into Teleport correctly. Run `tsh login --proxy=` to get valid certificates before +trying to start a PuTTY saved session. + +Note that if you are using a saved session for a leaf cluster using a root cluster's proxy, you must log into the root cluster +itself to be able to start a session against the leaf cluster. + +### `ERROR: No proxy address specified, missed --proxy flag?` + +You do not have valid `tsh` credentials locally. Run `tsh login --proxy=` to log in first, or provide the `--proxy` +parameter when running `tsh puttyconfig`. + + +## Uninstalling tsh + +To remove `tsh` and associated user data see +[Uninstalling Teleport](../management/admin/uninstall-teleport.mdx). + +## Further reading +- [CLI Reference](../reference/cli.mdx#tsh-puttyconfig). + diff --git a/docs/pages/reference/cli.mdx b/docs/pages/reference/cli.mdx index 104cb8f42e800..9faf6b814f258 100644 --- a/docs/pages/reference/cli.mdx +++ b/docs/pages/reference/cli.mdx @@ -312,6 +312,34 @@ $ tsh config $ tsh config >> ~/.ssh/config ``` +### tsh puttyconfig + +Adds a PuTTY saved session to the Windows registry for the currently logged in Windows user. + +``` +$ tsh puttyconfig [--leaf ] [login@]hostname +``` + +#### Flags + +| Name | Default Value(s) | Allowed Value(s) | Description | +| - | - | - | - | +| `-l, --login` | none | Linux username | Default Linux username to use. Will translate to SSH config's `User` option. | +| `-p`, `--port` | 3022 | port | Default SSH port to use. Will translate to SSH config's `Port` option. | +| `--leaf` | none | Leaf cluster name | Leaf cluster name to add to the saved session. | + +#### Examples + +```code +# Add a saved PuTTY session on 'node' for the user 'ec2-user' +$ tsh puttyconfig ec2-user@node + +# Add a saved PuTTY session on leaf-node for the user 'ec2-user' on the leaf cluster 'example.teleport.sh' +$ tsh puttyconfig --leaf example.teleport.sh ec2-user@leaf-node +``` + +See [full docs on `tsh puttyconfig` here](../connect-your-client/putty.mdx). + ### tsh apps ls List all available applications: @@ -1469,11 +1497,11 @@ proxy_templates: # Multiple templates can be provided. They are evaluated in order and the first # one matching will take effect. -- template: ... +- template: ... ``` -`tsh -J {{proxy}} ssh` and `tsh -J {{proxy}} proxy ssh` will attempt to match the -host server address `%h:%p` with the configured templates. For each replace rule set, +`tsh -J {{proxy}} ssh` and `tsh -J {{proxy}} proxy ssh` will attempt to match the +host server address `%h:%p` with the configured templates. For each replace rule set, the corresponding cli value will be set. If leaf certificates are required to connect to the node, `tsh` will automatically @@ -1492,7 +1520,7 @@ $ tsh ssh -J {{proxy}} node1.none.example.com ERROR: proxy jump contains {{proxy}} variable but did not match any of the templates in tsh config ``` -If the proxy variable `-J {{proxy}}` is not explicitly provided, then `tsh` will +If the proxy variable `-J {{proxy}}` is not explicitly provided, then `tsh` will still attempt to match a template, but will not fail when there is no match. Additionally, it will not replace the `proxy` value when explicitly set by the client. @@ -1503,7 +1531,7 @@ $ tsh ssh -J leaf2.us.example.com:443 node1.leaf2 $ tsh ssh -J leaf2.us.example.com:443 --cluster leaf2 node1 ``` -Proxy Templates can also be used with OpenSSH by setting the `ProxyCommand` +Proxy Templates can also be used with OpenSSH by setting the `ProxyCommand` in `~/.ssh/config` to use `tsh proxy ssh`. ```txt