StayLinked provides support for several features that are not part of the configuration panels available within the client. These configuration options are available through the Settings Deployment features of the StayLinked Administrator only by replacing the complete configuration files. This option can be found among the “All –“ options and is called Configuration File Transfer. Please refer to the Administrator User Guide for details using this method of settings management.
Multiple/Backup StayLinked Servers (servers.ini)
The purpose of this enhancement is to provide a mechanism by which the StayLinked Client can select from and connect to multiple StayLinked Servers and to support the ability of the StayLinked Client to fail-over to a backup StayLinked Server. Devices may also be configured with a connections.ini file, that is easily created within the client. Connections.ini can be copied to multiple devices using the same methods as a servers.ini implementation. Devices that require configuration options specific to each server address should use connections.ini.
Basic Implementation:
The new enhancement will only be available if the new SERVERS.INI file exists on the device. If this file does not exist, or the contents of the file are malformed, then the client will revert to the original functionality as provided by the contents of the STAYLINK.INI file. Be sure the file is not named server.ini as this is not a recognized file name and will not work.
Multiple Server Handling:
The SERVERS.INI file will provide the ability to specify multiple StayLinked Server to be available to the client for connections. When only a single server is specified, then the user will not be presented with a selection but will instead be connected directly to the server. If there are multiple server specified, then the user will be able to select from a menu that lists these servers. Once a connection is established to a server, that server will be the 'current server' and the connection will be persistent until the user 'Exits the Session'. If the client receives commands to 'Restart the Client', or receives new client software or new device settings, then the device should automatically reconnect to the same 'current server'. Session switching commands should also apply to the 'current server'.
Backup Server Handling:
If a backup server is specified, then special handling of connection failures will be processed. If the backup server is optional, then when a connection failure to the primary server occurs, the user will be presented with a menu of options. If the backup server is mandatory, and the 'failover retries' are exceeded, the client will automatically connect to the backup server. Once a connection to the backup server is established, it will be considered to be the 'current server' and handling will proceed as described in the 'MULTIPLE SERVER HANDLING' section of this document. If the connection to the backup server fails, then the entire backup processing mechanism will be reset, and the next connection attempt will be to the primary server.
SERVERS.INI Overview:
The SERVERS.INI file describes the list of StayLinked Servers and the backups that are available to the StayLinked Client. This file is stored in the 'Persistent' StayLinked folder on your device. If the file does not exist in the persistent folder, any cold boot operation may result in the loss of the file. If the SERVERS.INI file is transferred to the device using the Administrator’s reliable file transfer, then the file will be recognized by the StayLinked Client and handled appropriately, being transferred to persistent storage if possible.
SERVERS.INI Sections:
SERVERS.INI contains two sections.
Firstly, a [servers] section that will describe one or more StayLinked Servers
that will be made available to the StayLinked Client for connections. Secondly,
an [options] section that can describe options to control the conditions and
actions to follow when the primary selected server fails to connect.
[servers] Section:
Each server line, or key, in the [servers] section begins with server#' where the # refers to the number of the server entry beginning with one. It is recommended that these key names are sequential. Duplicate key names will cause one or in some cases, all of the lines to be ignored. Key values are limited to 10 entries. If there is only one server entry in this section, then the device will immediately connect to that server. If there are multiple servers defined in this section, then the device will display the list of available servers for the user to select from. Each comma-delimited entry in this file will describe a StayLinked Server Name, IP or Host Name, and Port. Optionally, the entry can also contain a backup IP or Host Name and Backup Port. Here is a sample of the contents of the [servers] section:
Note: that WinCE and Windows Mobile clients also support an option for medium, wifi or gprs. These would follow the port on any configuration line.
[options] Section:
The [options] section contains the
options that affect the behavior of these features. The following options are
available:
allow_quit – Describes whether or not a 'Quit' menu option will be displayed at the bottom of the server selection menu. Valid values are 1=Show the Quit option (Default), 0=Do not show the Quit option.
failover_optional – If a selected server also contains backup server data, then this option determines whether the failover is optional or mandatory. If optional, then the user will be presented with options when the client is unable to connect to the primary server. Valid values are 0=Mandatory, 1=Optional (Default) 2=Automatic (#2 added in client build 228 this option connects without prompting the user).
failover_retries – If the failover is mandatory, then this option describes how many retries will be attempted after the initial attempt before the client automatically tries to connect to the backup server. Valid Values are a range from 1 to 5 retries with a default of 2.
Excluding any of these items from the options section will use the normal default value in its place.
If failover is optional and the client fails to connect to the primary server (occasional host timeouts are expected in most environments and simply means the client dropped or transposed a packet during the handshake with the server), then a connection failure menu will be displayed like this:
Err: Host Timeout
——————–
1 – Retry Primary
2 – Use Backup
3 – Quit
If the user has selected to connect to the backup, and that connection fails, then a connection failure menu will be displayed like this:
Err: Host Timeout
———————
1 – Retry Backup
2 – Use Primary
3 – Quit
If failover is mandatory, and the client fails to connect to the primary server, then the dialog will display the following form, based on your specific server information:
After all retries to the primary have failed, the next connection attempt will be to the backup server. If the client fails to connect to the backup server, then the client will revert to the primary server.
After all retries to the backup server have failed, the client will return to the main StayLinked menu unless 'Always Auto-connect' is set. When 'Always Auto-connect' is set, the client will automatically restart the connection process from the beginning.
Server Selection Menu:
When there are multiple servers defined in the [servers] section of SERVERS.INI, then the user will be presented with a menu from which to select the desired server. Each menu option will use the Server Number and the Server Name to create the menu text. A sample server menu follows:
Select a Server
—————
1) WMS Server
2) PTL Server
3) Test Server
4) Quit
Session ID Management:
StayLinked tracks each session with a unique session ID number. These session IDs are managed by interaction between the client and server process. The following information is provided for reference only. Manually adjusting session ID values may result in lost or orphaned sessions.
If a device is allowed to connect to multiple servers, then it will track session IDs for each server. As always, the session IDs will be managed in the SESSION.INI file. If the device is not using the SERVERS.INI file, then the session information will be stored in the [defaults] and [alternate] sections like this:
If the device is using the SERVERS.INI file, then there will be a section created in SESSION.INI for each server like this:
Each alternate section applies only to servers using dual session licensing.
Share the post "Client Guide – Servers.ini"