Teleport
Using PuTTY and WinSCP with Teleport
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
This guide will show you how to use the Teleport client tool tsh
to add saved sessions for use
with PuTTY, 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 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.3 or higher. To download thetsh.exe
client, run the following command:curl.exe -O https://cdn.teleport.dev/teleport-v16.4.2-windows-amd64-bin.zipYou should then unzip the archive and move
tsh.exe
to your%PATH%
.NoteDo not place
tsh.exe
in theSystem32
directory, as this can cause issues when using WinSCP. You should use%SystemRoot%
(e.g.C:\Windows
) instead, which is already included in%PATH%
.If you do not have administrator rights on the Windows system you're using, you can use
%USERPROFILE%
(e.g.C:\Users\<username>
) instead - but note that you will not be able to runtsh
commands globally from the command line unless you are in the same directory astsh.exe
. -
PuTTY for Windows version 0.78 or higher. You can download the latest version of PuTTY from the PuTTY download page.
-
(optional) WinSCP for Windows version 6.2 or higher. You can download the latest version of WinSCP from the WinSCP download page
Summary
To add saved sessions to PuTTY:
- Sign into a Teleport cluster using the
tsh login
command:
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.
- 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 127.0.0.1:3022 company=acmecorp,env=aws,...
ip-172-31-34-128.us-east-2.compu... ⟵ Tunnel access=open,enhanced_reco...
ip-172-31-8-63 172.31.8.63:22 type=openssh
- 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:
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.
If you are adding a session for a registered OpenSSH node within your cluster (added with
teleport join openssh
), you must specify the sshd
port
(usually 22) when adding a session with tsh puttyconfig
:
C:\Users\gus>tsh puttyconfig --port 22 ubuntu@ip-172-31-8-63
Added PuTTY session for ubuntu@ip-172-31-8-63 [proxy:teleport.example.com]
You can also use tsh puttyconfig user@host:22
if you prefer.
- Sign into a Teleport cluster using the
tsh login
command:
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.
- 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...
- 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:
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
- Start PuTTY to see the saved sessions available for your cluster.
- Double-click a session to connect to the host through Teleport.
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:
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 <leaf cluster name>
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:
C:\Users\gus>tsh puttyconfig --leaf example.teleport.sh [email protected]
Added PuTTY session for [email protected] [leaf:example.teleport.sh,proxy:teleport.example.com]
Session naming
Sessions are named using the following schema:
Root clusters: <login>@<hostname> [proxy:<proxy address>]
Leaf clusters: <login>@<hostname> [leaf:<leaf cluster name>,proxy:<proxy address>]
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.
- 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.
- Click the Tools button at the bottom left, and choose Import Sites.
- 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 <user>@<host>
from a terminal as described above to add the sessions, then repeat this step.
- 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 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.
- 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.
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
?
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, port, 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?
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?
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.
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
WinSCP shows Server unexpectedly closed network connection
or Error 232: The pipe is being closed
when connecting
This error is usually caused when the tsh.exe
application is incorrectly placed in the C:\Windows\System32
directory. This
triggers a bug in WinSCP which causes the path to tsh.exe
to be erroneously replaced at runtime, leading to a connection
failure. This bug does not seem to affect PuTTY sessions.
Here are two locations where tsh.exe
can be stored which are not affected by this bug:
%SystemRoot%
(e.g.C:\Windows
- requires administrator privileges, and is included in%PATH%
by default)%USERPROFILE
(e.g.C:\Users\<username>
- does not require administrator privileges)
To fix this issue, follow these steps:
- Place the
tsh.exe
application into a different directory, as detailed above. - Re-run
tsh puttyconfig
for each PuTTY session in order to replace the configured path totsh.exe
inside the session. - Delete each saved session inside WinSCP.
- Re-import saved PuTTY sessions into WinSCP by following the process detailed in steps 2-3 above.
proxy: ERROR: access denied to <user> connecting to <proxy>
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
.
Connect failed [ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey], no supported methods remain]
You have provided an incorrect login username to the tsh puttyconfig
command when attempting to connect to an OpenSSH server.
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.
If the node is running OpenSSH rather than Teleport, you must make sure to specify the sshd
port when adding the session,
for example using tsh puttyconfig --port 22 user@host
or tsh puttyconfig user@host:22
.
proxy: direct dialing to nodes not found in inventory is not supported
This error usually means that you registered an agentless OpenSSH host (i.e. a host running sshd) without also providing the
port while running tsh puttyconfig
. Try re-adding the host with the correct port (22 in this example) by using
tsh puttyconfig --port 22 user@host
.
If you still get this error after fixing the port, make sure that the host you are trying to connect to appears in the output
of tsh ls
. Hostnames which do not appear in the output of tsh ls
are unavailable for connection.
Unable to use certificate file "C:\Users\<username>\.tsh\keys\<proxy>\<user>-ssh\<cluster>-cert.pub" (unable to open file)
You are not logged into Teleport correctly. Run tsh login --proxy=<proxy hostname>
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=<proxy hostname>
to log in first, or provide the --proxy
parameter when running tsh puttyconfig
.
ERROR: validity string for TeleportHostCA-<cluster_name>...
Any errors related to the validity string are caused by invalid formatting in the PuTTY registry key which holds the list of hostnames that should be trusted for a given host CA. Invalid formatting is generally caused by manual editing of host CA records in the PuTTY GUI or Registry Editor - this should never be necessary and is strongly discouraged.
To fix this error, load PuTTY and go to SSH -> Host Keys -> Configure Host CAs at the left hand side. Select the matching
TeleportHostCA-<cluster_name>
host CA record from the error and click Load. You can manually fix the entry under "Valid hosts this
key is trusted to certify" - the format must follow <hostname> || <hostname> || ...
- or you can click the Delete button.
Note that deleting a host CA record will mean you then need to re-run tsh puttyconfig
for every Teleport SSH service in that cluster
that you want to be able to access via PuTTY, even if the saved sessions still exist.
If this error appears during normal day-to-day operation, this is a bug and should be reported via GitHub.
Uninstalling tsh
To remove tsh
and associated user data see
Uninstalling Teleport.