As the key benefit of the StayLinked solution, the Server and Clients use a few different mechanisms to return users to their existing sessions. StayLinked should always return the user to where they left off, even in environments where devices can change network addressing or subnet. The only reason a user should not get back to their session is in cases where it has been intentionally ended. This may be by the telnet host due to inactivity, backup processes or other activities that terminate the telnet connection. This brief guide aims to describe the mechanisms, what can go wrong and solutions to these rare instances.
Client Unique ID (UID)
When a StayLinked Client is installed on a device, it populates a registry value with the default UID. During the startup of the Client, the default value will be automatically replaced with a unique value, typically the MAC address of the primary network adapter. Values that are not the default entry are left as-is.
The image to the right shows the ‘About’ screen of a Client. Not only does it show the current value, but it also includes a button that allows the registry entry to be reset to the default value. During the next startup, this would be replaced by the unique value determined by the StayLinked Client.
Any device connecting to the StayLinked Server will pass on this UID value, allowing the Server to identify devices even if they have changed network address or adapter.
Imaging and Cloning
One of the most common instances under the category, “what can go wrong,” is when devices are cloned or imaged for a ‘known good’ install. Replicating a populated UID value to multiple devices makes each device report the same UID to the StayLinked Server. This ‘less than unique’ value would cause devices to steal an existing session from another device with that same UID. When creating a device image, the UID should be reset before creating the image and before the Client is run again. The Client restart would trigger a rebuild of the UID value that is specific to that host device.
There are six methods of resetting the UID on a current device. Not all Clients support all of these options.
Option 1) Many Windows-based devices can use the ‘Reset UID’ button on the About screen as shown on the image at the top of this article. The About screen would be displayed by selecting the File menu and selecting the About option. Devices using the full screen mode setting will not display these menus and must be taken out of full screen mode in order to access the About screen.
Option 2) Android and Java Clients store the UID value as part of a persistent file called session.ini. For these clients, you can delete the session.ini and restart the client to generate a new UID. Note that these clients will not be able to recover a session left under an old UID. This means it’s important to clean up old sessions when you reset an android or Java client, since they become orphaned without a client owning the associated UID.
Option 3) Windows CE and Windows Mobile devices can use a registry file or manually edit the device registry back to the default value. On most devices, the registry value would be found in the following hive:
[HKEY_LOCAL_MACHINE\Software\Apps\eSP Stay-Linked]
; Reset UID
"eSP_UID"=string:A0DEADBEEF0D
This section can be copied to a text document with the .reg file extension and then manually merged on your device.
Option 4) Adjust the client configuration file staylink.ini with an entry for uid_override=XXXXXXXXXXXX where the 12-character value uses only hexadecimal values (0-9 and A-F) avoiding lower-case letters. Many clients v11 and higher support this entry to replace the standard method of retrieving a unique identifier.
Option 5) Create a Scan2Command barcode to reset the UID. These barcodes can be scanned into the StayLinked Client scan test. You should close existing sessions for this device and use the Tools > Scan Test option.
Option 6) Starting with Administrator version 15.5, the client setting for the UID override is available. This client setting should be configured for specific devices and can help avoid the need to manually find and configure remote devices. Be sure to set a value with exactly 12 characters in the Hexadecimal range 0-9 or A-F.
Be sure not to use the ‘Restart Client’ barcode if the device will be your image source. Create your image before the StayLinked Client is allowed to start again. These barcodes have been included in this article using the Code 128 symbology, but may need some print quality adjustments in order to be printed and readable by your device scanner.
When scanning these barcodes, the Randomize UID code should only be used on devices that are unable to normally return a unique value. Use the Reset UID and then Restart Client barcodes to immediately affect the UID on devices that were improperly cloned with a common UID.
Devices with tethered scanners must be configured properly for scanner-as-wedge before using these barcodes. More information on scanner-as-wedge can be found in the scanner-as-wedge technical reference article.
Devices that are already in a session will be unable to reconnect to that session if their UID is changed and the device reconnects to the StayLinked Server.
The Session ID
When a device establishes a connection to the StayLinked Server, that session will be assigned a session ID. This value is stored by the Client, allowing it to ask for existing sessions on the Server by name. This image of the Administrator shows the session ID as the first visible column in the connections list.
Double clicking on a session in this list will display the connection details. The unique ID, hardware address and IP address are just a few of the details provided in this panel.
Each Client writes the session ID to a local file on the device. This file, called session.ini allows the Client to check the last session ID when connecting to the StayLinked Server. Clients will pass a session ID of 00000 to the Server in order to ask for a new session.
It is important that file management utilities do not modify or replace this file as it may interfere with the session recovery features of the StayLinked Server.
Orphan Detection
The StayLinked Server Settings dialogue contains a checkbox for an ‘Orphan Detection’ feature. This will allow Clients requesting session ID 00000 to connect to an existing session if one is found to match the unique ID of that Client. Servers using multi-session licensing will always be provided a new session when session ID 00000 is requested.
Session Cleanup
Devices requesting an invalid session ID are not subject to orphan detection rules. As mentioned previously, if the session.ini is modified or replaced with an old or invalid session ID, the StayLinked Server will terminate any active sessions associated with the device’s Unique ID and provide the device with a new session.
The StayLinked Manager Log
During the connection process, the Client and Server complete a handshake to initiate a connection. The details of this handshake is documented in several places, including the Secure Communications Guide and Technical Reference for Host Timeout. The following samples have several values color-coded here to help identify them.
The details included in this string provide enough information for the Server to get the Client back to an existing session, or start processing for a new session.
This device had a later interruption in network communications, prompting it to query the StayLinked Server to confirm that the session was still valid. This ‘query session status’ is recorded in the Manager log file with the request and response.
These features work together to provide users with session reliability for their telnet connections. They also allow the StayLinked Server to transfer sessions between different Clients, or share a single telnet session among multiple devices using ‘session partnerships’ and sharing from the StayLinked Administrator. Sessions cannot be transferred between different telnet servers or between production and backup StayLinked Servers.
Share the post "Session Persistence"