FAQ

1. How to use X?

X should work out of the box if you did not skip the X-Server installation in the initial setup. Simply open a connection and start a X application (e.g. "xeyes" like you can see on one of the screenshots).
If this doesn' work, you need to make sure that a) the X-Server is installed and b) the X-Server is running. Both can be controlled in the Preferences menu (Preferences->X-Server). To install the X-Server, click on "Download" to download the file "VcXsrv-portable-1.17.2.0.zip" and after that select this file by clicking on "Install". To start the X-Server, click on the "Start X-Server" button.

2. How to use the "Copy Files" feature?

If you right-click a connection you can open up a WinSCP session by clicking on "Copy Files". WinSSHTerm sends the connection configuration to WinSCP, so there is no need for manually creating a session in WinSCP and this is a good thing. Usually WinSCP will open up the user's home directory. You can change this by highlighting the full directory path in PuTTY before clicking on "Copy Files". WinSCP will then open up and automatically try to cd into that directory.
To enable this feature, you need to make sure that the portable executable of WinSCP is installed (Preferences->Copy Files). If you need to change some WinSCP settings (e.g. configuring a proxy), you can do this with command-line parameters. For more information please have a look here and here.

3. Which keyboard shortcuts can I use in WinSSHTerm?

Besides the shortcuts from PuTTY, WinSSHTerm provides additional shortcuts which are listed in the menu (Navigate->Shortcuts).

4. I need to change some PuTTY settings, but I can't find it in WinSSHTerm

WinSSHTerm uses one shared PuTTY session (called "WinSSHTerm") for all connections. You can open PuTTY and manually change the session settings, which aren't configurable in WinSSHTerm and see if this works for you. However, if you manually change the session settings, then WinSSHTerm won't be fully portable any longer. All custom changes will be lost if you switch your computer or reset the PuTTY session file "WinSSHTerm". If you find yourself in this situation please contact me.

5. How to update WinSSHTerm?

If you're using the .msi installer edition, then simply download the new version and install it. To update the portable edition, download the new version, extract the zip and replace the file "WinSSHTerm.exe". In order to update the embedded tools like PuTTY or WinSCP, go to Preferences menu, download the new version and overwrite the old files by clicking on "Install".

6. Pressing the TAB key in the terminal client switches the tab

This bug was fixed in version 1.3.6. It is possible to switch the tabs with CTRL+TAB and CTRL+SHIFT+TAB - this is the standard keyboard shortcut for switching tabs in MS Windows.
Edit: This still seems to be an issue in very rare cases, which until now could not be reproduced. If you run into this problem, pressing the CTRL-key once should revert the normal behaviour.

7. The PuTTY terminal is UTF-8 encoded, but not WinSCP

WinSCP checks the environment variable $LANG on the remote system to decide whether to enable UTF-8 or not. If your $LANG is set to "POSIX", UTF-8 will not be enabled. To force UTF-8 in WinSCP, set the $LANG to e.g. "en_US.UTF-8" or add the command-line parameters "/rawsettings Utf=1" in Preferences->Copy Files.

8. I've lost the master password

Without the master password it's not possible to decrypt the stored passwords, including the password for the shared connection file and its template variables. If you have lost your master password, then manually delete the file "key" in the "config" folder and start WinSSHTerm. It will start without the password prompt, but all encrypted data will be deleted.

9. Setting custom terminal color

Edit: Since version 2.2.0 custom terminal colors are supported and set up under File->Preferences->Terminal->Color Scheme->Edit

Currently WinSSHTerm supports only the color schemes "WinSSHTerm" and "PuTTY". However, it is possible to use a custom color scheme by following these steps in the exact order:

1.) Start WinSSHTerm and go to File->Preferences->Terminal
2.) Choose Color Scheme -> ignore and click on Ok
3.) Import the custom color scheme reg file into the PuTTY session "WinSSHTerm" (you can also manually edit the colors with PuTTY)
4.) Open up a new connection and you should see the new color scheme

Please note, that this is only a workaround (more info in section 4.).

10. Sorting the connections tree (workaround)

Sorting the connections tree automatically is currently not supported. However, as the connections are stored in a XML file, you could sort the connections by using an external program like XML Sorter (mirror). In XML Sorter, just open your "connections.xml" as source (be sure to make a backup of this file and close WinSSHTerm before). If you want to sort all connections by name, then select Options->Sort by specific attributes->Name and click on "Sort". Now wait until the sort process finishes. You should see the sorted XML in the "After" textbox. To persist the changes select Target->Overwrite source file and click on "Save".

11. Connections and Config windows are incorrectly displayed after update

In some rare cases, after updating WinSSHTerm, these windows might be incorrectly displayed and you can't control them. Even resetting the layout (Views->Reset Layout) might not help. In this case close WinSSHTerm and delete the file "layout.xml" in the config folder. After starting WinSSHTerm the default layout should be displayed.

12. PuTTY: "Incoming packet was garbled on decryption"

Since 2.22.0: By using "SSH Proxy" as Jump Server Mode (File->Preferences->Terminal) there will be a popup window if the host key of the jump server is not trusted.
 
If you are trying to connect to a remote server not directly, but by doing a SSH hop over a jump server, this error might occur. It occurs, when the host key of the jump server has changed, and the new host key is not trusted yet by PuTTY. To fix this, open up a connection to the jump server - you should see a security alert - and verify, that the new host key fingerprint is valid. If it's valid, click on Yes to permanently trust it. It should now be possible again to hop over the jump server.

13. What do you do with donations?

Mainly I use the money to buy (sadly expensive) code signing certificates for WinSSHTerm and to pay hosting fees for the download server. I'm also making donations to other projects from time to time, like e.g. PuTTY, as you can see on the screenshot below.
 

14. Error loading connections.xml / preferences.xml

In rare cases these files might get corrupted when the system crashes while WinSSHTerm is persisting to the file system. In that case, exit WinSSHTerm and go to the config/ folder. There should be a file like 'connections_<DATE>_<TIME>.xml' / 'preferences_<DATE>_<TIME>.xml'. Rename this file to 'connections.xml' / 'preferences.xml' and start WinSSHTerm again.

15. PuTTY changing position inside window

A user (thanks to Adrian P.) reported strange behaviour of PuTTY/KTTY - changing its position inside the window when the mouse cursor passes the scrollbar. It turned out that a utility by Lenovo caused this behaviour - the "Lenovo Auto Scroll Utility", which shows up as "virtscrl.exe" in the task manager. Disabling this tool solved the issue.

16. Window focus issues

WinSSHTerm uses Windows Hooks in order to get notified when a PuTTY terminal gets activated. These hooks can't be set up in managed code, that's why there is the need for the unmanaged library 'WinSSHTerm.dll'. This is unfortunately hacky but I haven't found a better way yet.
By using hooks it is e.g. possible to bring the whole WinSSHTerm window to front when the user clicks into a terminal, or to detect a PuTTY Fatal Error. Experience has shown that this works quite well - however, there are some rare cases where the hooking mechanism suddenly stops working. If you find yourself in this situation, it is not enough to restart WinSSHTerm - you'll have to log your Windows user off and on again.

17. Tunneling your ssh session through a jump server

Since 2.22.0: By using the new feature "SSH Proxy" as Jump Server Mode (File->Preferences->Terminal) there is no need for Plink any more. Trusting the jump server's host key is much easier than the old way.
 
Sometimes you are not allowed to directly ssh into your server - you have to ssh into a bastion host (or jump server) at first, and then establish the ssh connection to your server from there.
If you are in this situation, WinSSHTerm can automatically set up a tunnel to your jump server, so you can directly ssh into your server. To set it up, please do the following:
1.) The tunnel is internally set up with Plink, so be sure to install Plink under File->Preferences->Plink
2.) Create a new connection to your jump server and connect to it. The important step here is to accept the host key from the jump server and save it in the registry. Important: If the host key of the jump server is not stored in the registry (or is a wrong key), the tunnel can not be set up (see also FAQ point 12).
3.) Now create a new connection and fill in the connection details of your destination server under „Connection“.
3b.) Additionally, fill in the connection details of your jump server (from step 3) under „Jump Server“ and enable the feature by setting „SSH Proxy“ to enabled.
4.) If you use a local ssh key to connect to the final destination make sure to enable agent forwarding (Session->Agent forward->Allow). If you use a passphrase protected ssh key to the jump server either use Pageant and add the key there (Files->Preferences->Pageant) or provide the passphrase to the key in the password field of the jump server connection setting. It is recommended to use Pageant for security reasons.
5.) If you now double-click on the connection, you should directly log into your destination server.

18. Port forwarding

In case you want to use port forwarding, you can do this with PuTTY command line arguments "-L" or "-R". If you e.g. have a web server running on port 80 on your remote server, and you want to be able to access the web server by entering "http://localhost:8080" in your local browser, then you can enter "-L 8080:localhost:80" into the field "Cmd-line Args" and open the connection to forward your local port 8080.

19. Debug Logging

In case you have problems with establishing a connection with PuTTY or WinSCP and you can't find the reason you can enable debug logs:

PuTTY
1.) In the configuration for the connection you want to enable debug logs, choose a new file for logging ouput under "Session->Log file name", e.g. C:\putty.log
2.) Set "Session->Logging" to "SSH packets"
3.) Now open the connection - after that you should see the logs in the file "C:\putty.log"

WinSCP
1.) Make sure the option "Append custom command-line parameters" is checked under File->Prefernces->Copy Files
2.) Append these parameters into the text field below
/log="C:\winscp.log" /loglevel=0
3.) Now open the connection - after that you should see the logs in the file "C:\winscp.log"

20. Switching from the portable to the installer edition

If you are already using the portable edition of WinSSHTerm and decide to use the installer edition, you can do following:
1.) Install WinSSHTerm by double-clicking the .msi package
2.) Make sure there is no instance of WinSSHTerm running (also no WinSCP and VcXsrv)
3.) Copy the subfolders "config" and "tools" from your portable edition to your Documents folder "%userprofile%\Documents\WinSSHTerm\"
4.) Now you can run the installer edition of WinSSHTerm

21. Setting custom environment colors (PROD, DEV,...)

In the configuration of your connection, set the color as a rgb value (separated with a comma) in the field Connection->Env Color. Example for red background: 125,0,0
It is recommended to use different template variables for different groups of connections.
 
Changing multiple colors is optionally possible if the Environment Color Mode 'Change terminal colors' is selected (File->Preferences->Terminal->Environment Color Mode).
 
Syntax: r_2,g_2,b_2[;n:r_n,g_n,b_n]*
 
n: Describes the PuTTY color id, valid values are 0, 1 and 3 to 21
 
0  -> Default Foreground
1  -> Default Bold Foreground
2  -> Default Background
3  -> Default Bold Background
4  -> Cursor Text
5  -> Cursor Colour
6  -> Black
7  -> Black Bold
8  -> Red
9  -> Red Bold
10 -> Green
11 -> Green Bold
12 -> Yellow
13 -> Yellow Bold
14 -> Blue
15 -> Blue Bold
16 -> Magenta
17 -> Magenta Bold
18 -> Cyan
19 -> Cyan Bold
20 -> White
21 -> White Bold
 
A basic example for "Env Color" with multiple color changes:
234,30,30;0:244,230,200;1:244,230,200;5:244,230,200;8:244,230,200;9:244,230,200;10:244,230,200;11:244,230,200;12:244,230,200;13:244,230,200;14:244,230,200;15:244,230,200;16:244,230,200;17:244,230,200;18:244,230,200;19:244,230,200

22. Using a custom PuTTY session (e.g. for legacy telnet)

Since version 2.2.4 you can set a custom PuTTY session (other than "WinSSHTerm") for a connection under Session->Custom. So just load the session "WinSSHTerm" in PuTTY, make your changes (like setting the protocol to telnet), save to a new session and set the new session name in WinSSHTerm. It is currently marked as beta, because it breaks WinSSHTerm's portability, which means if you want to run WinSSHTerm on another computer you have to manually move your custom PuTTY session(s).

23. Automatically trust new or changed SSH host keys

For security reasons (man-in-the-middle attack) PuTTY or Plink requires user interaction when the host key is not cached in the registry or the key has changed. This can be a problem when you e.g. try to execute commands non-interactively with Script Runner. If you run into this problem you can automatically trust the keys by clicking on "Trust host keys" in the Script Runner window. It will send the character "y" to all selected servers and then close the connection. If the key is already trusted, you'll see the login prompt in the output field.

Please note: Be sure to review all fingerprints of the added host keys afterwards in the output field, as there is a risk of a man-in-the-middle attack This is especially important when you're not connecting to servers in your local network.

24. Load a connection group on startup

WinSSHTerm supports the command line argument /congroup, which stands for "connection group". It will automatically open the connection group when WinSSHTerm starts. The syntax is:

WinSSHTerm.exe /congroup="My Group"

25. PuTTY session opens up outside of WinSSHTerm (when using Chocolatey)

EDIT: Since version 2.12.0 WinSSHTerm will automatically detect shims and handle them correctly

You can set the custom location for PuTTY to point to the binary, which is managed by Chocolatey. However, you have to make sure to set the custom location to the actual binary, and not to the "shim", which is generated by Chocolatey. If you install the Chocolatey packages "putty.portable", the "shims" will be created in the "bin/" directory. They are not supported by WinSSHTerm.

So, for the package "putty.portable", please set the custom location in WinSSHTerm to
C:\ProgramData\chocolatey\lib\putty.portable\tools\putty.exe

For the other tools, like WinSCP, VcXsrv, Plink and so on, using the "shims" is supported by WinSSHTerm.

26. Using variables

There are following built-in variables available for each connection
{{CON.NAME}} -> name of the connection
{{CON.HOST}} -> hostname
{{CON.USER}} -> SSH username
{{CON.PASSWD}} -> SSH password
{{CON.PORT}} -> SSH port
{{CON.DESC}} -> description
{{CON.CUSTOMID}} -> a custom id of your choice
These can be used in Scripts, Script Runner, Multi-Input Paste, in the command-line arguments for WinSCP and VcXsrv, and in the connection configuration itself  (local and shared). Be sure to enable "File->Preferences->General->Enable variables globally".
Additionally, you can set your own variables under File->Preferences->Connections->Template Variables. Variables with hidden values can only be used when a master password is set.

27. X11 forwarding and switching to another user

1.) Login as root user to remote server and make sure that X11 forwarding is working correctly
2.) Then run these commands as root:

echo $DISPLAY > /tmp/X_display
xauth list $DISPLAY > /tmp/X_cookie

3.) Switch to another user with sudo:

sudo su - <user>

4.) Now run these commands:

export DISPLAY=$(cat /tmp/X_display)
xauth add $(cat /tmp/X_cookie)

5.) Now X11 forwarding should work. When opening a new SSH session this procedure has to be repeated.
 

28. Connection Filter

The include and exclude patterns support regular expressions.The connections list contains the folder name(s) of a connection, the connection name, and additional properties, seperated by the hash sign. These properties are: Host/IP, Port, User, Custom Id.
 
Example: To filter all connections with Host/IP beginning with "192.168" and User "root", you could use following include pattern:
 
^.*<192.168.*#.*#root#.*>$

29. Become root with sudo without entering the password

Use-case: You aren't allowed to login into the remote host as root user. Instead you need to login with your personal user account and then switch to root user with "sudo su -". You will need to enter your password.

In WinSSHTerm, you can set up a connection so that you can switch to root by just entering "s".

Steps:
  1. Make sure that you have set a Master Password (File->Master Password)
  2. In the connection configuration enter the password in the password field (make sure your password doesn't contain the single quote character)
  3. In the field "Login Cmds" enter following: 

    echo '{{CON.PASSWD}}' | sudo -Si; s(){ sudo su -; }; export -f s

  4. If you now connect to the host, you should be able to become root by typing "s" and hitting the enter key

30. Installing WinSSHTerm (.msi package)

The default install scope is "user". That means when double-clicking the msi package, WinSSHTerm will install only for the current user, without the need for admin privileges. To install WinSSHTerm "system wide", you can pass the parameter MSIINSTALLPERUSER="", e.g.

.\WinSSHTerm-2.35.2-x64.msi MSIINSTALLPERUSER=""
 
Or, if you like to install with "msiexec", you need to pass the parameter "ALLUSERS=1":
 
msiexec /i WinSSHTerm-2.35.2-x64.msi ALLUSERS=1
 

31. Execute a script after login

You can configure your script for each connection in the field "Login Cmds". Example:

echo "Hello"; echo "World"

There are some cases, where this won't work. In that case you can wrap your script inside a function and export it. You would then need to call the function manually to execute the script. Example:

f() { echo "Hello"; echo "World"; }; export -f f

Now you can run the script by typing "f" and pressing enter.
You can also use variables in "Login Cmds" (see point 26).

32. Set locations from environment variables

If you want to set the custom location in an automated manner, you could set any of these system-wide ('machine') environment variables:
 
# path to putty.exe
WINSSHTERM_TERMINAL_CUSTOM_PUTTY_LOCATION
 
# path to pageant.exe
WINSSHTERM_PAGEANT_CUSTOM_LOCATION
 
# path to puttygen.exe
WINSSHTERM_PUTTYGEN_CUSTOM_LOCATION
 
# path to plink.exe
WINSSHTERM_JUMP_SERVER_CUSTOM_PLINK_LOCATION
 
# path to WinSCP.exe
WINSSHTERM_COPY_FILES_CUSTOM_WINSCP_LOCATION
 
# path to vcxsrv.exe
WINSSHTERM_X_SERVER_CUSTOM_VCXSRV_LOCATION
 
These environment variables will be read when WinSSHTerm starts. The custom location will be set if not already configured. In case you want to make sure WinSSHTerm always uses the location from these environment variables, you can append "_X" to the variable names.
 

33. How to use OpenSSH certificates

There is a screencast that shows how to use OpenSSH certificates:

https://www.youtube.com/watch?v=Cjv5aqkUh2M

You'll need following files:
 
User authentication:
  • your private key in PuTTY format, e.g. my_user_private_key.ppk (generated by you, e.g. with Puttygen)
  • your OpenSSH certificate file, e.g. my_user_certificate.pub (generated with your public key by the one who manages user access)

Trusting remote hosts:

  • the public key file of the OpenSSH CA, e.g. ca_public_key.pub (generated by the one who manages the host certificates)

34. Why is the tab not closing when the session closes?

By default, if you close a PuTTY session with e.g. CTRL-D the tab title will be marked as disconnected, but the tab won't be closed. The reason for this behaviour is simple: the server might close the session unexpectedly - if then the tab closes, you would loose all of the terminal history.

However, if you would like the tab to close when the session is closed, you can set "File->Preferences->Terminal->Close Window" to "on clean exit". This way the tab will close on e.g. CTRL-D.

35. How to use Smart Cards or FIDO keys?

PuTTY doesn't support it, however there is an open-source project "PuTTY CAC" available on GitHub here. As it uses PuTTY's code base, it should be no problem to use the PuTTY CAC binaries in WinSSHTerm. There is a GitHub issue about this topic.

36. How to use the Auto-Type feature (KeePass) in WinSSHTerm?

Make sure the option "File->Preferences->General->Custom PuTTY window title" is enabled, so that the PuTTY window will contain the string "user@host". Now you can set the string

*{UserName}@{URL}*

as target window in the Auto-Type tab of your KeePass entry to make sure KeePass will send the password to the correct terminal window with the global hotkey "CTRL+ALT+A".

37. How to set up a ssh tunnel with multiple jumps?

It is possible with the internal Launch Tool Multiple Jump.

38. Where can I see the docs for the Launch Tool feature?

The documentation is available in the GitHub repository Launch Tools.

 

 

Subscribe to: Posts (Atom)