docs: Add WinSCP troubleshooting step and tsh.exe path advice #42697
Conversation
webvictim
added
documentation
backport/branch/v13
backport/branch/v14
no-changelog
github-actions
bot
requested review from
Joerger,
mmcallister,
ptgott,
r0mant,
ravicious,
rosstimothy,
xinding33 and
zmb3
|
🤖 Vercel preview here: https://docs-10ndcvp4s-goteleport.vercel.app/docs/ver/preview |
| @@ -27,6 +27,11 @@ You will learn how to: | |||
|
|
|||
| You should then unzip the archive and move `tsh.exe` to your `%PATH%`. | |||
|
|
|||
| <Admonition type="note"> | |||
| Do not place `tsh.exe` in the `System32` directory, as this can cause issues when using WinSCP. | |||
| You should use `%WINDIR%` (e.g. `C:\Windows`) or `%USERPROFILE%` (e.g. `C:\Users\<username>`) instead. | |||
There was a problem hiding this comment.
I don't think %USERPROFILE% is in Path by default on Windows. At least not on my installation of Windows 11. When I googled "windows how to add exe to path", I didn't see people recommend this location either.
Should we recommend creating a folder in %USERPROFILE%, adding it to Path and then moving tsh.exe there instead? This complicates the instructions, but I don't see a better way.
FWIW, Connect adds the folder with the bundled tsh to Path during installation.
%WINDIR% is in system's Path for sure, though it's called %SystemRoot%, which generally seems to be preferred.
There was a problem hiding this comment.
You're correct that %USERPROFILE% isn't on the path by default. With this in mind, I'm going to change the guidelines to recommend installing tsh.exe to %SystemRoot% (i.e. C:\Windows) by default and only using %USERPROFILE% if they don't have admin rights.
The other alternative is that we walk people through creating C:\Program Files\Teleport or similar, unzipping/moving tsh.exe there and then permanently adding it to the path with setx /M PATH "%PATH%;C:\Program Files\Teleport" - but this has the risk of messing up their PATH variable globally and also requires admin rights to do, when we could just use something that's already on the PATH.
There was a problem hiding this comment.
That sounds good. It's a shame that there's no better alternative on Windows. Placing stuff in %SystemRoot% feels wrong, but I guess it's the closest thing to something like /usr/bin.
There was a problem hiding this comment.
I agree, it's a mess. Also the fact that you can't natively unzip from the command line - you have to invoke PowerShell 😵💫
Co-authored-by: Paul Gottschling <[email protected]>
public-teleport-github-review-bot
bot
removed the request for review
from stevenGravy
|
🤖 Vercel preview here: https://docs-nb56lu2rk-goteleport.vercel.app/docs/ver/preview |
|
🤖 Vercel preview here: https://docs-3tuu72bij-goteleport.vercel.app/docs/ver/preview |
|
🤖 Vercel preview here: https://docs-r44d4fn4t-goteleport.vercel.app/docs/ver/preview |
|
🤖 Vercel preview here: https://docs-idc2bs732-goteleport.vercel.app/docs/ver/preview |
|
🤖 Vercel preview here: https://docs-ou5pv63we-goteleport.vercel.app/docs/ver/preview |
|
🤖 Vercel preview here: https://docs-iyc3qs3g7-goteleport.vercel.app/docs/ver/preview |
|
🤖 Vercel preview here: https://docs-jzc6jynl5-goteleport.vercel.app/docs/ver/preview |
|
@webvictim See the table below for backport results.
|
* docs: Add WinSCP troubleshooting step and tsh.exe path advice * Other tsh.exe locations * Apply suggestions from code review Co-authored-by: Paul Gottschling <[email protected]> * Update suggested PATH and use ordered list * Use SystemRoot instead of WINDIR and flip order * Update admonition * Update install-tsh.mdx * Update putty-winscp.mdx * Spelling error --------- Co-authored-by: Paul Gottschling <[email protected]>
* docs: Add WinSCP troubleshooting step and tsh.exe path advice * Other tsh.exe locations * Apply suggestions from code review Co-authored-by: Paul Gottschling <[email protected]> * Update suggested PATH and use ordered list * Use SystemRoot instead of WINDIR and flip order * Update admonition * Update install-tsh.mdx * Update putty-winscp.mdx * Spelling error --------- Co-authored-by: Paul Gottschling <[email protected]>
* docs: Add WinSCP troubleshooting step and tsh.exe path advice * Other tsh.exe locations * Apply suggestions from code review Co-authored-by: Paul Gottschling <[email protected]> * Update suggested PATH and use ordered list * Use SystemRoot instead of WINDIR and flip order * Update admonition * Update install-tsh.mdx * Update putty-winscp.mdx * Spelling error --------- Co-authored-by: Paul Gottschling <[email protected]>
#42881) * docs: Add WinSCP troubleshooting step and tsh.exe path advice * Other tsh.exe locations * Apply suggestions from code review * Update suggested PATH and use ordered list * Use SystemRoot instead of WINDIR and flip order * Update admonition * Update install-tsh.mdx * Update putty-winscp.mdx * Spelling error --------- Co-authored-by: Paul Gottschling <[email protected]>
#42882) * docs: Add WinSCP troubleshooting step and tsh.exe path advice * Other tsh.exe locations * Apply suggestions from code review * Update suggested PATH and use ordered list * Use SystemRoot instead of WINDIR and flip order * Update admonition * Update install-tsh.mdx * Update putty-winscp.mdx * Spelling error --------- Co-authored-by: Paul Gottschling <[email protected]>
#42886) * docs: Add WinSCP troubleshooting step and tsh.exe path advice * Other tsh.exe locations * Apply suggestions from code review * Update suggested PATH and use ordered list * Use SystemRoot instead of WINDIR and flip order * Update admonition * Update install-tsh.mdx * Update putty-winscp.mdx * Spelling error --------- Co-authored-by: Paul Gottschling <[email protected]>
While investigating a customer issue with using WinSCP, @programmerq discovered an interesting Windows/WinSCP bug relating to path replacement which is only triggered when
tsh.exeis spawned from theSystem32directory.This PR adds a troubleshooting step to the WinSCP docs explaining how to work around this issue, and adds information wherever the docs instruct people to install/extract
tsh.exeto inform them not to useSystem32(which is pretty bad practice anyway, and requires administrator rights)