TTY PTY support in Windows OpenSSH

On Windows 10+ and Windows server 2019+, OpenSSH uses the features provided by console. OpenSSH ssh client uses console ability to parse the incoming VTSequence from ssh server. On the server side, OpenSSH sshd server component uses conpty support provided by the Microsoft console team. If you are using downlevel OS (Windows 10 / Windows server 2019 below OS version) then please be aware of some restrictions listed below.

SETUP

Windows SSH client to Linux/Unix/macOS (*nix) SSH server

If you want to have the best experience while using utilities like vi, top, man, etc. while connected from a Windows SSH client to a *nix server, you should configure your terminal to use an xterm-like rendering mode.

Unfortunately, this rendering mode is only included with Windows 10. If you're not on Windows 10, you may have more luck using a third-party terminal emulator or console host like Cmder or ConEmu.

1. Open a shell from which you want to use ssh (either powershell or cmd).

2. Right-click the application icon in the upper-left and the window and select Properties.

3. Ensure that Use legacy console (requires relaunch) is unchecked:

   

4. In the Layout tab, set the Screen Buffer width and Window Size width to >= 90:

   

   All of these changes will persist within the same shortcut to cmd or powershell. If you want to change the defaults for new shortcuts, select Defaults in Step 2 instead of Properties.

5. Set the TERM environment variable to xterm:

   set TERM=xterm 
   

   In PowerShell you can also use the $env: namespace to edit this variable:

   $env:TERM = 'xterm'

   Both of these methods will only persist for the current session. If you want this to happen every time you start PowerShell, you can leverage PowerShell profiles.

   If the TERM environment variable is not found then the SSH client code sets the TERM as 'xterm-256color' for the duration of SSH session.

Linux/Unix/macOS SSH client to Windows SSH server

1. Set the TERM environment variable to xterm:

   export TERM=xterm

Windows SSH Client to Windows SSH server

1. Set the non-legacy console mode in the console properties,
   Make sure you uncheck the "use legacy console"
   

2. Set the Screenbuffer width, window size width to >= 90.
   

3. If your windows client machine is **windows 10 or above ** and if you have any issues,

   a) exit the current ssh session (if any)

   b) set the environment variable SSH_TERM_CONHOST_PARSER to 0
   c:\test> set SSH_TERM_CONHOST_PARSER=0
   c:\test> set SSH_TERM_CONHOST_PARSER (This should show "0")

   c) start a new ssh session.

   d) if you are NOT able to reproduce then it is the windows 10 console issue. Please let us know by filing an issue, so that we will update the known issues. FYI, the fix should come from the windows 10 console team but not from the SSH team.

   e) if you are able to reproduce then file an issue.

Known windows 10 console issues (These will be fixed by the windows console team)

When connected to unix ssh server

a) vim command, intermittently the file is opened in the Replace mode.
b) top command, clears the previous screen contents.
c) window resize is not supported because of a bug in conhost.exe (conhost.exe is a windows 10 module to parse ANSI sequences).

When connected to windows ssh server and using powershell

a) while executing an unknown command (abcdef) in the powershell, the last line ( + FullyQualifiedErrorId : CommandNotFoundException) is not displayed on the console

Implementation details

PTY

Windows versions before Windows 10 1809 did not have built-in support for a pseudoterminal.

Windows version of OpenSSH server implements a VT100 PTY by intercepting Windows Console events. This is implemented in ssh-shellhost.exe, connected to sshd via std i/o. At a high level, ssh-shellhost.exe acts as an intermediary between sshd and a Windows console applications performing the following:

• interprets incoming VT100, processes and calls Windows Console IO
• processes Windows Console (output) event queue, translates them to VT100 and spits out on stdout.

TTY

Windows console previously did not have the capability to process any incoming terminal control codes. Support for xterm is added in Windows 10.

To support downlevel platforms (down till Windows 7), a VT100 interpreter is implemented in Windows OpenSSH client (ssh.exe) to support typical TTY scenarios. Although this works well when talking to Windows targets, there are limitations and known issues when dealing with interactive applications on Unix like top, vi, etc.

If you are using the openssh client,
a) Windows 10+ OS then windows console (cmd.exe/powershell) has the support to interpret the VT sequences received from the SSH server. We simply pass the raw VT sequences to the console (cmd.exe/powershell). If you are facing any issues then it should be fixed by the windows console team.

 If you want to use the inbuilt [VT100](https://en.wikipedia.org/wiki/VT100) ANSI parser (that's part of the openssh client) then set the environment variable "SSH_TERM_CONHOST_PARSER" to 0.

b) Prior versions of windows 10 OS, the raw VT sequences will be parsed by the inbuilt VT100 ANSI parser that's part of the ssh.exe. We have fixed most of the issues. We have no plans to extend to VT100+ sequences. After 9999 you will have to refresh the screen, otherwise the data will only be rendered on the last line.

 If you want support for the VT100+ sequences then please upgrade to windows 10+ OS or use the third party tools like putty, Cygwin, etc.

Testing

We have tested different scenarios,

1. Windows client (cmd.exe / powershell) to windows server
2. Windows client (cmd.exe / powershell) to Linux server
3. Linux client to windows server
4. Third party ssh tools like putty/Cygwin to windows server

While making any terminal code changes, please make sure below manual test cases are passed

1. All the arrow key functions should work properly (up, down, left and right arrows).
2. The backspace, delete, home, end functions keys should work properly.
3. "cls" should clear only the visible window (windows 10+ OS) / should clear entire buffer (prior versions of windows 10 OS).
4. When connected to unix ssh server, the basic commands like vi, top, man, clear, etc should work properly.