diff --git a/CHANGELOG.md b/CHANGELOG.md index 793d410f895d6..31518ca674c9d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -172,7 +172,7 @@ tsh on Windows now supports the `tsh puttyconfig` command, which can easily configure saved sessions inside the well-known PuTTY client to connect to Teleport SSH services. -For more information, see [docs](docs/pages/connect-your-client/putty.mdx). +For more information, see [docs](docs/pages/connect-your-client/putty-winscp.mdx). #### Support for TLS routing in Terraform deployment examples diff --git a/docs/config.json b/docs/config.json index 68323f76fc983..c1ec83b236cfd 100644 --- a/docs/config.json +++ b/docs/config.json @@ -954,8 +954,8 @@ "slug": "/connect-your-client/teleport-connect/" }, { - "title": "Using PuTTY", - "slug": "/connect-your-client/putty/" + "title": "Using PuTTY and WinSCP", + "slug": "/connect-your-client/putty-winscp/" }, { "title": "Database GUI Clients", @@ -3105,6 +3105,11 @@ "destination": "/management/dynamic-resources/terraform-provider/", "permanent": true }, + { + "source": "/connect-your-client/putty/", + "destination": "/connect-your-client/putty-winscp/", + "permanent": true + }, { "source": "/server-access/guides/openssh/", "destination": "/server-access/guides/openssh/openssh/", diff --git a/docs/cspell.json b/docs/cspell.json index 19b3a41797197..f0c3785c88e6c 100644 --- a/docs/cspell.json +++ b/docs/cspell.json @@ -838,6 +838,7 @@ "winadj", "windowsaccountname", "windowsdesktop", + "winscp", "winserver", "workgroups", "wtmp", @@ -864,4 +865,4 @@ "flagWords": [ "hte" ] -} \ No newline at end of file +} diff --git a/docs/img/connect-your-client/winscp-1.png b/docs/img/connect-your-client/winscp-1.png new file mode 100644 index 0000000000000..79db262681dcd Binary files /dev/null and b/docs/img/connect-your-client/winscp-1.png differ diff --git a/docs/img/connect-your-client/winscp-2.png b/docs/img/connect-your-client/winscp-2.png new file mode 100644 index 0000000000000..a39037c8d2ed5 Binary files /dev/null and b/docs/img/connect-your-client/winscp-2.png differ diff --git a/docs/img/connect-your-client/winscp-3.png b/docs/img/connect-your-client/winscp-3.png new file mode 100644 index 0000000000000..9f50be49c1868 Binary files /dev/null and b/docs/img/connect-your-client/winscp-3.png differ diff --git a/docs/img/connect-your-client/winscp-4.png b/docs/img/connect-your-client/winscp-4.png new file mode 100644 index 0000000000000..47b51b900443f Binary files /dev/null and b/docs/img/connect-your-client/winscp-4.png differ diff --git a/docs/img/connect-your-client/winscp-5.png b/docs/img/connect-your-client/winscp-5.png new file mode 100644 index 0000000000000..b070dde676047 Binary files /dev/null and b/docs/img/connect-your-client/winscp-5.png differ diff --git a/docs/img/connect-your-client/winscp-6.png b/docs/img/connect-your-client/winscp-6.png new file mode 100644 index 0000000000000..aebc66b44bd46 Binary files /dev/null and b/docs/img/connect-your-client/winscp-6.png differ diff --git a/docs/pages/connect-your-client/putty.mdx b/docs/pages/connect-your-client/putty-winscp.mdx similarity index 76% rename from docs/pages/connect-your-client/putty.mdx rename to docs/pages/connect-your-client/putty-winscp.mdx index f67ed99fdbe4e..db4d9fad7aca1 100644 --- a/docs/pages/connect-your-client/putty.mdx +++ b/docs/pages/connect-your-client/putty-winscp.mdx @@ -1,22 +1,25 @@ --- -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 +title: Using PuTTY and WinSCP with Teleport +description: This reference shows you how to use PuTTY to connect to SSH nodes and WinSCP to transfer files 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. +It will also show you how to optionally use these saved sessions with [WinSCP](https://winscp.net) to transfer +files from SSH nodes using SFTP. + 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. - +- (optional) Import a saved PuTTY session into WinSCP, then start an SFTP session to transfer files from an SSH node. ## 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: +- The Teleport `tsh.exe` client, version 14.0.3 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 @@ -26,6 +29,7 @@ You will learn how to: - 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). +- (optional) WinSCP for Windows version 6.2 or higher. You can download the latest version of WinSCP from the [WinSCP download page](https://winscp.net/eng/download.php) ## Summary @@ -156,6 +160,64 @@ Root clusters: `@ [proxy:]` Leaf clusters: `@ [leaf:,proxy:]` + +## Using WinSCP to transfer files over SFTP + +You can import a saved session from PuTTY to WinSCP, which allows you to connect to an SSH node +transfer files to and from it. + +1. Start WinSCP. + +If you don't see the Site Manager "Login" dialog appear with a list of sessions to connect to when WinSCP starts, +click the **Tabs** menu, choose **Sites**, then **Site Manager...** to show it. + +
+![WinSCP Site Manager window](../../img/connect-your-client/winscp-1.png) +
+ +2. Click the **Tools** button at the bottom left, and choose **Import Sites**. + +
+![Click 'Tools', then choose 'Import Sites...'](../../img/connect-your-client/winscp-2.png) +
+ +3. Check the box next to any saved PuTTY sessions that you wish to import into WinSCP for use, then click the "OK" button. + +If you don't see sessions matching the hosts that you want to connect to, close this box and run `tsh puttyconfig @` +from a terminal [as described above](#summary) to add the sessions, then repeat this step. + +
+![Choose PuTTY sessions to import and click OK](../../img/connect-your-client/winscp-3.png) +
+ +4. To tell WinSCP it should trust and load saved Host CAs from PuTTY, click **Tools** again at the bottom left, +then choose **Preferences...** + + + You can skip steps 4 and 5 if you've completed the process as this user on this PC before. + + +
+![Click 'Tools', then choose 'Preferences...'](../../img/connect-your-client/winscp-4.png) +
+ +5. Click the **Security** section at the left, then check the **Load authorities from PuTTY** checkbox under +the *Trusted host certification authorities* section and click **OK** to exit. + +
+![Click 'Security', Check 'Load authorities from PuTTY' then click OK](../../img/connect-your-client/winscp-5.png) +
+ +6. Choose the host to connect to from the list at the left-hand side and click **Login**. You can also start the session +by double clicking on its name if you like. + +
+![Choose the host from the list and click Login](../../img/connect-your-client/winscp-6.png) +
+ +Uploading or downloading files using WinSCP through Teleport will generate audit events. + + ## Frequently asked questions ### Do I need administrator rights on my machine to run `tsh puttyconfig`? @@ -196,10 +258,7 @@ 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 +Yes, WinSCP version 6.2 and higher support validation using SSH host certificates which is needed to connect using Teleport. ### Can I use an alternative Teleport authentication method (`tsh login --auth`) with saved sessions? diff --git a/docs/pages/reference/cli/tsh.mdx b/docs/pages/reference/cli/tsh.mdx index c854f2d92b035..09e90cb605933 100644 --- a/docs/pages/reference/cli/tsh.mdx +++ b/docs/pages/reference/cli/tsh.mdx @@ -184,7 +184,7 @@ $ tsh puttyconfig ec2-user@node $ tsh puttyconfig --leaf example.teleport.sh ec2-user@leaf-node ``` -See [full docs on `tsh puttyconfig` here](../../connect-your-client/putty.mdx). +See [full docs on `tsh puttyconfig` here](../../connect-your-client/putty-winscp.mdx). ## tsh apps ls