User Manual

Thank you for purchasing the Georgia SoftWorks Windows NT Telnet Server software. You will be pleased with the performance and robustness provided with this product. Ease of use will be a significant time saver when using the Georgia SoftWorks Windows NT Telnet Server software. Complicated keyboard sequences are not required to map to the actual keys you want to send. The Georgia SoftWorks Windows NT Telnet Server software was developed to meet a need in the market that allows users to operate in a fast, reliable and uncomplicated fashion.

Windows NT is transformed into a truly multi-user environment with the Georgia SoftWorks Windows NT Telnet Server software. Remote administration, full support for DOS Legacy applications, superior user control and Telnet Session Monitoring will allow you to utilize Windows NT as never before.

Product Description

Our Telnet Server provides a level of robustness that is a cut above the competition. Industrial quality orphaned session detection and elimination including NTVDM's and attempted graceful termination of DOS legacy applications upon link and client PC failures are unique features to the Georgia SoftWorks Windows NT Telnet Server software.

Logon Scripting provides system administrators with unmatched control over user connections. One function of Logon Scripting allows the user to automatically enter specific applications upon connection. Logon Scripting can also restrict the user to only execute a specific application. Logon Scripting can do much more!

Server Software

The Georgia SoftWorks Windows NT Telnet Server is the software installed on your Windows NT computer. This software is responsible for establishing connections and spawning agent processes that manage each session. The Georgia SoftWorks Windows NT server software enforces the number of allowed simultaneous sessions.

Agent Process

A telnet session is created each time a connection is established. A connection is established when a user logs on to Windows NT system using a Telnet Client. For each session that is created the Georgia SoftWorks Windows NT Telnet Server software spawns an agent process. The agent process is responsible for managing and communicating with the user session. Screen optimizations are performed by the agent process to facilitate faster data transfers. The capability of a configurable server side inactivity timer exists for use by the agent process to help identify link or remote PC failures.

Client Software

The Georgia SoftWorks Telnet Client is proprietary software that runs on remote PCs and utilizes advanced features offered in the server software. Other optimizations are included to enable this to be the fastest Windows NT Telnet software on the market.

The Client software contains a configurable heartbeat timer that notifies the agent process of its presence. This mechanism helps to identify link or remote PC failures.

It is recommended that the Georgia SoftWorks Windows NT Client software be used although it is not required. The Georgia SoftWorks Windows NT Telnet Server is RFC 854 compliant which allows any 3rd Party Telnet Client to be used. However many of the advanced features of the propriety client will be forfeited.

Installation

Installation is simple and quick. The same installation program installs the server software and the client software. The installation software will prompt you for a full or client only installation if on a Windows NT system and automatically install client software if on a Windows 95 system.

Server

Installation of the server software is simple. Run the setup.exe program. From Windows NT perform the following:

Run the setup.exe program.

1. The Welcome screen of the setup program is displayed and you are reminded and urged to exit all windows programs before continuing. You are also reminded that you must have administrative privileges to install this program. Click Continue.

2. The Installation options screen is displayed. The choices are Full Install or Install Client Only software. For Windows NT systems that you want clients to connect select Full Install using the Radio Buttons. The Full Install installs the Server Software and the Client software. Click Continue.

3. A screen is displayed indicating the directory that the Georgia SoftWorks Windows NT Telnet Server will be installed. The default is C:\Gs_tnet. You may change the installation directory at this time. Click Continue.

4. The Setup Succeeded screen is displayed. The service has been installed and is automatically started.

5. A "Program Group" has now been created. It will contain 3 shortcuts. One is the Georgia SoftWorks Telnet Client, the second is the Registration shortcut, the third is the uninstall program.

This is how you register.

Note: If you are installing the 30-day trial copy you do not need to register the software. Skip this step. If you enter an invalid registration key the 30-trial will expire.

1. Double click on the Registration Shortcut
2. You are prompted that the Telnet Server application must be installed before the Registration software will run. Click Continue.
3. Enter the Registration Key that is enclosed with the software you received. If you purchased the software electronically then the registration key was e-mailed to you.
4. Upon entry of a valid key, you will get the prompt "Registration Succeeded". Click OK.

Client

This is how you install the client software.

Installation of the Client software is simple. Run the setup.exe program. From Windows 95 or Windows NT perform the following:

Run the setup.exe program.

1. The Welcome screen of the setup program is displayed and you are reminded and urged to exit all windows programs before continuing. The setup program recognizes if it is a Windows NT system and prompts you for either a Full Install or a Client Only install. If this is a Windows NT system then select Client Only using the Radio Buttons. If this is a Windows 95 system then you are prompted for installation of the Georgia SoftWorks Windows NT Telnet Client. Click Continue.

2. A screen is displayed indicating the directory that the Georgia SoftWorks Windows NT Telnet Client will be installed. The default is C:\Gs_tnet. You may change the installation directory at this time. Click Continue.

4. The Setup Succeeded is displayed.

5. A "Program Group" is created. It contains one shortcut, the Georgia SoftWorks Telnet Client.

UN-Install

To uninstall the Georgia SoftWorks Windows NT Telnet Software follow these instructions.

1. Click the Start button on the Windows NT Task bar - go to Programs
2. Find the Georgia SoftWorks Telnet line - To the right select uninstall and follow the instructions. To reinstall the software you will need to re-register the software.

How to use the Georgia SoftWorks Windows NT Telnet Software

Georgia SoftWorks Client

Follow these instructions to open the Georgia SoftWorks Client window.

1. Click the Start button at the bottom left corner of your screen.
2. Click Programs
3. Move the mouse cursor to "Georgia SoftWorks Telnet Server" entry.
4. Click to the right where you see "GS Telnet Client"

At this point, the Client window is open and you will get the host prompt.

At this prompt, you should enter the hostname that you wish to connect. The hostname is the name your Windows NT computer is referenced by via TCP/IP. This can be a text string or an actual IP address.

Example:

The login ID must be a valid Windows NT login id.

Example:

This is the password associated with the Login ID. It will not be displayed when typed.

This is an optional field. If you do not wish to connect to a specific domain then you may simply press "<enter>". Otherwise type in the domain you want to connect.

3rd Party Clients

The Georgia SoftWorks Windows NT Telnet Server will work with any RFC 854 compliant 3rd party client. Please see the vendor's instructions for configuration of the 3rd party client.

The procedure for connecting with a 3rd party client is similar to connecting with the Georgia SoftWorks client (see above).

Upon connecting with a 3rd party client you will be prompted to select a terminal emulation mode. Choose the desired emulation by selecting the appropriate number. Be sure to set the 3rd party client emulation mode to the same emulation as the one selected on the server.

The terminal emulation options available are

• DEC VT-100
• DEC VT-220/320/420
• SCO Console
• AT386

Enter 0 for DEC VT-100 emulation, 1 for DEC VT-220/320/420, 2 for SCO Console emulation and 3 for AT386 emulation.

If you do not want to be prompted for the emulation mode each time you log on using a 3^rd party client then you may set an environment variable on a per user basis using Logon Scripting (described later in the User Manual).

The environment variable for the terminal emulation is:

For example to select SCO Console emulation you would enter:

in the Logon Script for a particular user.

NOTE: No spaces are allowed when setting environment variables.

For example:

Graphic Characters

Third party clients do not always handle graphic characters and commands as expected. The Georgia SoftWorks Windows NT Telnet Server is flexible in providing options for handling graphic characters with 3^rd party clients. If you are unsure of which graphics mode to select the typical progression is the order that the selections are presented. The first works for all, the next is more specialized and so on. Feel free to experiment to determine the best graphics mode for your 3^rd party client. The graphics mode prompt indicates the recommended selection when SCO Console emulation is selected.

This simply replaces PC graphics characters with the "asterisk" character,

For VT emulation's the system converts the PC Graphic Characters to ACS and will temporally invoke Special Graphics character sets. PC Graphics without ACS equivalents will be converted to the "asterisk" character.

For SCO Console the system will inject appropriate escape sequences to display the graphic characters.

Pass PC Graphics characters without changes:.

This will pass any chars >= 0x80 without any changes.

Pass all characters from PC Screen without changes:.

This will pass all characters from the NT screen, your client software may have trouble with handling ASCII values for some of control characters like 0x08 (backspace).

If you do not want to be prompted for the graphics mode each time you log on using a 3^rd party client the you may set an environment variable on a per user basis using Logon Scripting. The environment variable for the graphics mode is:

For example to select star graphics character substitution you would enter:

in the Logon Script for a particular user.

NOTE: No spaces are allowed when setting environment variables. For example:

Many times programs are developed to work with monochrome monitors or terminals. In this situation you can choose between a color and monochrome presentation. After the graphics mode options are presented the color or monochrome options are presented. The prompt

Do you want ANSI Colors? [Y/N]:

If you want a Color presentation choose "Y". If you want a Monochrome presentation choose "N".

If you do not want to be prompted for the Color or Monochrome presentation each time you log on using a 3^rd party client the you may set an environment variable on a per user basis using Logon Scripting (described later in the User Manual).

The environment variable for the Color or Monochrome presentation is:

For example to select a color presentation you would enter:

in the Logon Script for a particular user.

And to select a monochrome presentation you would enter:

in the Logon Script for a particular user.

If the monochrome mode is selected the color mapping is performed as described below. For each character on the screen:

If background intensity is set then the blink attribute is set.

If foreground intensity is set then the bold attribute is set.

If the character is blue then the underscore attribute is set.

If background intensity is greater than foreground intensity then the inverse attribute is set as follows:

I = .3 * R + .6 * G + .1B

The intensity bit itself is not used in the above calculation. The attributes are additive.

This is how to change the registry key for the AltPrefix.

Note: (you must be on the Windows NT system that the Georgia SoftWorks Windows NT Telnet Server is installed. However you may connect to the Windows NT Registry from a remote location).

The key is:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ GS_Tnet\Parameters\AltPrefix

The new AltPrefix will take effect for all new sessions.

Terminating a session

Type exit at the client window prompt followed by the ENTER key and the session will terminate and the window will clear and then close.

TTY Name

The Georgia SoftWorks Windows NT Telnet Server creates a tty name on a per session basis. This is available for viewing or use by customer created programs.

The environment variable created is:

And is set to /dev/ttypxxx, where xxx

represents the socket number (handle) for user's session.

Heartbeat - Specifying a Client Timeout value

To aid in the detection of failed links or failed remote PC's the Georgia SoftWorks Client software supports a Client Timeout value. The client will send a heartbeat to the server at specified time intervals. At installation, this value is set to 300 seconds. This can be changed using the shortcut properties.

If the server does not receive data from the client in the specified time, the connection is terminated. The data can be keyboard, or mouse input as well as the heartbeat. When keyboard or mouse data is transmitted, or when a heartbeat detected the server's timer is restarted.

The heartbeat time is specified as an optional command line argument in seconds.

specifies a heartbeat time of 30 minutes (1800 seconds = 30 minutes).

To change the Client Heartbeat

1. Single click on the GS Telnet Client Shortcut.
2. Right click, properties will be displayed, click on properties
3. Select the Shortcut Tab.
4. Change Target command line to reflect the new heartbeat timer. The command string c:\gs _tnet\gs_clnt.exe /H300 is the default. The H300 parameter is the heartbeat count in seconds. 300 is 5 minutes. You may change or delete this parameter.
5. Click on apply. The new heartbeat time interval takes effect when you log in.

Server Side Inactivity Timer

If data (keyboard or mouse events) is not received from a client within the specified server side inactivity time then the client session is terminated. . The Server Side Inactivity Timer is used only if the client side heartbeat is not used.

This timer is a registry key value and is in seconds. The key is:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ GS_Tnet\Parameters\InactivityTimeout

The default value is 0xffffffff that is -1. (That is disabled.)

This is how to change the registry key for the Server Side Inactivity Timer.

Note: (you must be on the Windows NT system that the Georgia SoftWorks Windows NT Telnet Server is installed. However you may connect to the Windows NT Registry from a remote location).

The new InactivityTimeout will take effect for all new connections that do not have a client heartbeat configured.

Logon Scripting - automatic execution of DOS applications and more

Logon Scripting is an advanced feature that allows the system administrator unmatched control over the user sessions. Associated with each User Login Id is a directory that will execute batch files upon connection. One of two optional batch files can be executed. One is named k_start.bat and the other is c_start.bat.

One use of these batch files is to allow automatic execution of a DOS application upon connection.

k_start.bat - This file runs upon connection and after its completion the user may get the system prompt. This batch file may set environment variables, establish network connections, run TSR's etc.

c_start.bat - This file runs upon connection and after its completion the session terminates. This can be used to restrict the user to a certain application. Even if the user executes a control-c or something similar this will not allow access other than what is specified in the batch file on the NT computer.

The batch files are set up by the system administrator for each user in the system. They must be in the directory

Of course InstallationPath and UserLoginID is replaced with the actual values.

If both k_start.bat and c_start.bat exist then only c_start.bat is executed. You may call k_start.bat from c_start.bat.

Here is an example script to allow automatic execution of a Physicians Office Application "medical.exe" upon connection for the user login id (nurse). The Physicians office application is in the directory c:\medical.

Step 1. Create directory

Step 2. Create batch file k_start.bat

Step 3. Add line to k_start.bat

Step 4. Save file and exit.

Now when the User login id "nurse" connects to the Windows NT system via telnet the application medical.exe will automatically be started. When the user exits the medical package, the Windows NT Command line prompt is displayed allowing other activity to occur.

Here is an example script that will allow the User login id (bill) only to execute the amortization program amortize.exe. The amortization program resided in the directory d:\amor

Step 1. Create directory

Step 2. Create batch file c_start.bat

Step 3. Add line to c_start.bat

Step 4. Save file and exit.

Now when the User Login ID "bill" connects to the Windows NT system via telnet the application amortize.exe will automatically be executed. When the user exits the amortization package, the telnet session will terminate.

Global Logon Scripting

There are situations where the system administrator may want to have the same logon script executed by all the users upon connection. Instead of creating a logon script for each and every user, a single logon script can be created that will be executed by all users upon connection. The Global Logon script operates in the same manner as a normal logon script except for the location of the script files. The system administrator may put the k_start.bat or c_start.bat file in the subdirectory SCRIPTS (under the install directory). The server looks first for k_start.bat or c_start.bat in user's subdirectory and will not use the global script if it can find user's script.

Here is an example script to allow automatic execution of a Physicians Office Application "medical.exe" upon connection for ALL users that do not have a c_start.bat or k_start.bat in their logon script directory. The Physicians office application is in the directory c:\medical.

Step 1. Create batch file k_start.bat in the SCRIPTS directory (under the install directory).

Step 2. Add line to k_start.bat

Step 3. Save file and exit.

Now when the any user (unless they have their own login script in their logon script directory) connects to the Windows NT system via telnet the application medical.exe will automatically be started. When the user exits the medical package, the Windows NT Command line prompt is displayed allowing other activity to occur.

Graceful Termination of DOS Applications

The Georgia SoftWorks Windows Telnet Server is unique in that in case of a link or remote PC failure we attempt to gracefully terminate the executing DOS application, therefore saving important data that may otherwise be lost. Many applications are terminated by sending a sequence of characters to the application such as ESC-ENTER. Applications may have specific sequences. We allow a termination string to be defined as an environment variable in the k_start.bat or c_start.bat file. When a session is to be terminated due the client heartbeat timer expiring or the server side inactivity timer expiring then the defined termination string will be sent to the associated application. Approximately 3 seconds later the session is terminated if still running.

The following control key designators are defined.

• shift-
• alt-
• ctrl-

The following special characters are defined.

• ESC
• ENTER
• F1
• F2 and so on through F12

Also a special operator is defined.

• Sleepxx

This special operator will pause the output to the shell for xx seconds. This gives the application time to process the input. This is very useful when saving files to disk and for applications that flush the keyboard buffer.

We will continue to use the amortization program from example 2. However, we will assume that a standard menu exists for the application. A File menu item exists that is invoked by alt-f. The list of items in the File menu list includes s for saving the work and alt-f for opening the file menu list again and then x for exiting the application. Next follows the ",e,x,i,t,ENTER" to gracefully close the shell.

Step 1. Create batch file c_start.bat

Step 2. Add this line to c_start.bat

d:\amor\amortize.exe

Step 3. Add this line to c_start.bat (note: there are no spaces in following the "=")

SET LRA_TERMINATION=alt-f,s,sleep5,alt-f,x,e,x,i,t,ENTER

Step 4. Save file and exit.

Now when the User ID "bill" connects to the Windows NT system via telnet the application amortize.exe will automatically be executed. If the session is terminated due to system timeouts the termination string alt-f,s,sleep5,alt-f,x will cause the following sequence of events to occur.

First Alt-f to be sent to the application (This opens the file menu).

Second s is send to the application (for saving the file).

Third, the Sleep5 causes 5-second pause to allow the application time to save the files,

Fourth alt-f to open the file menu list again,

Fifth an x is sent to the application to exit.

Finally ",e,x,i,t,ENTER" is send to the shell which terminates the session.

Other examples of termination string definitions are:

SET LRA_TERMINATION=alt-f,x,e,x,i,t,ENTER

SET LRA_TERMINATION=F2,alf-f,x,e,x,i,t,ENTER

SET LRA_TERMINATION=ESC,ENTER,e,x,i,t,ENTER

Client Scroll Bars

You may enable scroll bars on the Windows NT client window. This is accomplished by changing the buffer size for the DOS window. You must be careful that the application can handle a modified buffer size. Unpredictable display results will occur if this is not the case.

Monitoring other Telnet Sessions

Included with the Georgia SoftWorks Windows NT Telnet Server is a powerful administrative, development and training tool - the Session Monitor. The session monitor is a stand alone utility that allows users within a certain group to connect to an existing Telnet session and observe the screen exactly as the client sees the screen. This connection only allows monitoring. You may use this utility as a local NT user or as a user connected via Telnet.

At this point you are observing the telnet session as if you are the user on that session. To exit the monitor depress the <ESC> key.

Session Monitoring Privileges.

To participate in Session Monitoring a user must belong to the group Gwtn Monitors. The system administrator must first create the group Gwtn Monitors. Next all users allowed to use the Session Monitor must be added to the group. You will have to restart the Windows NT server after creating the group and adding users. Windows NT does not instantaneously update the group membership after the user manager is closed.

Session Monitoring Uses.

There are many uses for session monitoring a few are listed.

• Quality Assurance - A supervisor can monitor data entry of employees.
• Training - A senior application user can remotely help a trainee understand and use a application.
• Debugging - A developer can remotely observe an application phenomenon that a user is describing.
• Administrative - A system administrator can ensure that users are using/setting up resources properly.
• Security - Administrator monitor users that are using telnet.

Programmatic Access to the Telnet Server

The Telnet Server communicates with the client through a WINSOCK socket. A protocol/mechanism is provided that allows a custom application to take and release control of the socket. Objects involved in taking and releasing control of the socket are passed through environment variables as are described below.

• GWTN_HSOCKET - This environment variable holds the value of the handle of the open socket. Note: Never close or otherwise destroy the socket.
• GWTN_GET_I - This environment variable holds the name of the WIN32 event that when signaled notifies the telnet server that the custom application wants to take control of the input from the client.
• GWTN_RLS_I - This environment variable holds the name of the WIN32 event that when signaled notifies the telnet server that the custom application wants to release control of the input from the client.
• GWTN_GET_O - This environment variable holds the name of the WIN32 event that when signaled notifies the telnet server that the custom application wants to take control of the output to the client.
• GWTN_RLS_O - This environment variable holds the name of the WIN32 event that when signaled notifies the telnet server that the custom application wants to release control of the output to the client.
• GWTN_ACK - - This environment variable holds the name of the WIN32 event that when signaled notifies the custom application that the request is granted.

Note1: All of the above mentioned events are autoreset events.

Note2: The above environment variables are automatically injected into the session's environment and will vary from session to session. Please do not attempt to modify those variables or set them in the autoexec files or Control Panel/System/Environment.

Please see the file interface.c included on the installation disks for a code sample. Interface.c contains a short program that takes control of the input and output and echoes characters to the client until a lowercase q is encountered.

Discussion: Orphaned NTVDM's and Windows NT Telnet Servers

NTVDM's are NT Virtual DOS Machines. For Windows NT to run DOS programs, NT creates a NT VDM that provides a DOS environment for the DOS program to reside.

When DOS applications are executed a NTVDM is created. A normal Telnet scenario is to connect to a Windows NT system and run a DOS application. NT will create a NTVDM. This is all fine and normal.

Normally during a Telnet session running a DOS application, upon completion of the application the user will exit the application properly. In this situation the NTVDM is properly terminated.

However problems occur when a Telnet session running a DOS application abnormally terminates.

The Telnet session will normally terminate however the NTVDM will not terminate. This leaves what is called a orphaned NTVDM. Some term this rouge or phantom NTVDMs or processes.

These orphaned NTVDM's are a serious problem to the NT System. They will start consuming all the processing resources of the Windows NT system that results in the severe degradation of all other processes on the system. This is not just a slight slowing down of the system but a slowing down to the point of the system being useless by most users standards. The most common way to clear the NTVDM is to reboot the NT system. However if you are skilled you can kill the orphaned processes.

Any abnormal terminal of a client can cause an orphaned NTVDM. One easy way to create an NTVDM with telnet simply to power off the Client PC while running a DOS program via Telnet. For example:

1. Telnet from a remote Client PC to an NT System.
2. Run a DOS application. (Such as Edit, Norton Commander etc).

1. Typing Ctrl-Alt-Delete on the server and select the Task List
2. Select processes and observer the NTVDM that was created.

1. Power down the Client PC.
2. On the Telnet Server, observe that the NTVDM is still running. You will notice that after a few minutes the processing percentage will increase to 90+%.

Having multiple Telnet sessions connected running DOS applications when an abnormal termination occurs can exacerbate this problem.

Frequent scenarios for abnormal terminations

• Power Failure for Client PC.

1. Power Hit in building
2. Breaker trip,Client PC or Power strip accidentally unplugged

• Client PC powered down without properly exiting the DOS application
• Client PC OS locks up.
• Link Failure

The Georgia SoftWorks Windows NT Telnet Server automatically provides advanced detection and elimination for orphaned NTVDM's. Unlike others that claim to handle this serious problem, the Georgia SoftWorks Windows NT Telnet Server actually detects and eliminates these process consuming tasks in a remarkably quick time minimizing the impact on other users and tasks on the system. The Georgia SoftWorks Windows NT Telnet Client accomplishes detection via the configurable heartbeat timer and third party telnet clients utilize the configurable Server Side Heartbeat Timer. Upon detection sophisticated algorithms are used to identify orphaned NTVDM and eliminate them.

Technical Support

For Technical Support.

In order to keep Technical Support Free please help us to keep our cost down.

• Gather all relevant system information.
• Write your question down. This not only helps us but also helps you in articulating the question.

If the question is not an emergency, please use e-mail at techsupport@georgiasoftworks.com. We try to respond within 24 hours.

Or Call 706.265.1018 EST, M-F 9:00 a.m. to 5:00 p.m. and have your registration key ready