How to use SSH to access Reality on Windows

Generally newer UNIX and Linux systems will automatically include SSH client and server software. Establishing a terminal connection to databases on these systems is normally just a case of configuring the 'Communications' in RealLink to use the 'SSH' protocol rather than 'LAN'.

This is not the case, yet, on Windows servers. It is necessary to find a third party product. The Bitvise SSH Server has been used with some success. The installation of this product and the configuration necessary to access it using RealLink is covered below.

Installing the Bitvise SSH Server (BSS) on Windows

Download BSS from

Run the downloaded executable as administrator, setting the checkbox to agree to the license agreement. Take the defaults to install a new Bitvise SSH server as a new default server in 'Program Files'.

Select 'Standard edition' for 30 day trial period, or 'Personal edition' depending upon the expected usage. A command window shows the installation of BSS and when done a dialogue reports 'installation completed'. Dismiss this dialogue and the following SSH control panel is displayed.

The 'Easy Settings' screen

This screen is displayed after installation, or it can be accessed later by selecting 'Open easy settings' from the 'Server' tab of the BSS control panel. The following values are suggested:

The 'Enable trace logging' option helps in the tracking down of connection issues, it should be cleared when all is working.

It is not necessary to set up any Windows accounts or Virtual accounts.

Press 'Save changes' when all done.

Testing BSS

In the 'Server' tab in the BSS Control Panel press 'Start Server', the control panel shows that the 'Bitvise SSH Server Service is running.

Start/Administrative Tools/Services will show the Bitvise SSH Server as started with a startup type of 'Automatic', from a command prompt 'netstat -an|find "22" ' will show that something is listening on TCP/IP port 22, the ssh port.

From another computer, such as a UNIX or Linux system with the ssh utility, test that an ssh connection can be established to the Windows server.

$ ssh joe@joespc

Here 'joe' is the Windows user name on PC named 'joespc'.

Be aware, if BSS is later re-installed then there will be a file ~joe/.ssh/known_hosts which needs to be edited to remove the entry for joespc.

Respond 'yes' to the query on authenticity of the system joespc. Then, when prompted, enter joe's Windows password.

A DOS command prompt is presented providing access to joespc, for instance DIR will show the contents of the current folder.

Issue 'exit' to close the connection to joespc.

If there are any issues with establishing a connection, then from the 'BSS Control Panel' select the 'Open log folder view' and double-click the most recent log file.

Although ssh connections can now be established to the Windows system and it is feasible to run Reality to connect to databases on the Windows system only Reality term type 6, VT220, is supported and that has limitations. This is solved by configuring the BSS to re-route incoming ssh connections to a telnet server – the Reality session manager.

Configuring BSS to reroute ssh connections to the Reality session manager

The BSS provides the means to redirect incoming ssh connections to a local telnet server, in the example of a Reality server this will be the Reality session manager, normally listening on port 23

In the 'Server' tab on the BSS Control Panel select 'Edit advanced settings.

Under 'Access control' select 'Windows groups'.

There will normally contain one entry, 'Windows group type' of 'Everyone', if not press the 'Add' button to create one.

Double click the entry.

Select 'Terminal and exec requests', set the 'Shell access type' to 'Telnet server', all the defaults can be left as they are, address and port 23, unless the Reality session manager has been configured to listen on a different port using netadmin.

Note: While in this example port 23 is still used, this is not a Telnet Server, just Reality session manager "listening" on port 23 internally within the Server. For security reasons sites may prefer not to use the "standard telnet port of 23", in which case port 26 (an unassigned port for any use) could be configured for both Bitvise as below and Reality using netadmin.

Press OK to return to the 'Windows groups' screen.

Press OK to return to the BSS Control Panel.

Press Close.

From the computer used above to test ssh connections to the Windows system enter the same ssh command as above, like:

$ ssh joe@joespc

This time the Windows user password is prompted for and then the 'Reality Session Manager' log on prompt is displayed and the user can log on to Reality in the normal way. Having logged on in this way the Reality TERM type can now be  set to match the terminal type of the client.

Making ssh connections from RealLink

Press File/Open. Enter 'Filename', 'joessh' for example.

Press Communications. Enter 'Host Name' or TCP/IP address. Select 'Protocol' of 'SSH'. Press OK to return to the 'Open' dialogue, press OK to close this dialogue.

Press Setup/Terminal Emulation, select desired emulation, typically P12. Press OK.

Press File/Save to save this new configuration.

Press Connection/Connect, check 'Filename' is correct, 'joessh' for example. Press OK to establish the connection. A user ID/password dialogue is displayed, enter the Windows user ID and password.

The Reality session manager on the target system displays the log on prompt. Enter the required Reality user ID.

As before, if there were any issues connecting to the Reality database select the 'Open log folder view' from the BSS Control Panel and select the most recent log file.


Explanation of Terminal handling in Windows console applications

When Reality is run as a Windows console application, i.e. from a command shell, Reality needs to translate Reality screen control sequences to console screen operations. Reality does this by emulating a VT220 and translates a subset of the VT220 screen control sequences to console screen operations.

This scenario becomes more complicated when running Reality from a console session running within a SSH shell on the Bitvise SSH Server, and probably most other SSH servers on Windows.

When the BSS is configured to start a normal command prompt it needs to translate between the console screen operations of applications being run to screen control sequences to transmit to the remote client, these sequences conform to the terminal type specified by the client when the ssh connection was established.

So for example the client may be using a VT100 terminal type, Reality will translate VT220 screen control sequences to console screen operations, the BSS command shell then translates these console screen operations to VT100 screen control sequences for display by the client.

The BSS facility to redirect ssh connections to the Reality session manager allows Reality started in this way to use any supported terminal type as normal; there is no console and thus console screen operations do not occur with this type of connection.

Back to articles