Server Installation Guide Linux Platform

StayLinked Solution Components

StayLinked™ is a software product that provides a complete solution for managing your wireless terminals and their host telnet sessions. This section describes the components of the StayLinked system.

Wireless Terminal

StayLinked Thin Client
Dynamic or Static IP Address
Server IP Address and Port Number
Wireless Network Infrastructure

Administrator Workstation

StayLinked ™ Administrator
Windows 8.1 or newer
Windows 2012 Server or newer
Workstation is not dedicated to StayLinked

Server Hardware

StayLinked ™ Server
Local Compatible VT Application
Access to other 5250, 3270 or VT Hosts
StayLinked ™ Java Programs

Planning and Installation

As with any software, some planning is necessary to ensure a successful installation. Use this planning information to help you install the StayLinked components.

Installation Summary

• Ensure that all minimum requirements have been met on the Linux Server where StayLinked will be installed.
• Designate a Windows PC that will be used to manage the StayLinked Server. This PC need not be dedicated to the administration task. You can install the StayLinked Administrator onto the same Windows machine where the StayLinked Server is installed.
• Install the StayLinked Server Software onto the Linux Server.
• Start the StayLinked Server using the ‘strserver.sh’ script.
• Install the StayLinked Administrator onto the designated management PC.
• Start the StayLinked Administrator and connect to the StayLinked Server.
• Take note of the Server S/N that will be displayed in the Administrator Server List.
• Provide the Server S/N in order to acquire your StayLinked License Key.
• Use the StayLinked Administrator to install your StayLinked License Key.
• Flash your RF device with the appropriate StayLinked Client software and configure the device.
• Use the StayLinked Administrator to install keyboard maps for your RF devices.
• Use the StayLinked Administrator to configure your Telnet Host or Hosts.
• Connect the StayLinked RF device to the StayLinked server and get to work.

Linux Server Requirements

StayLinked Servers range from a few connections to thousands. Use of advanced product features such as screen recognition and modernization can result in higher required system requirements. For the most reliable performance, please review the Server Tuning documentation or consult the StayLinked Support team.

Hardware Requirements for the Linux Server

Most modern servers will exceed these requirements on a hardware machine, and virtualized servers should not be minimally configured without review of actual resource utilization. Servers shared for multiple applications should take into consideration the maximum load induced by each application and allow for adequate resources at all times. Machines in excess of 5 years old may require additional resources to compensate for slower relative performance. The following suggested values may be more than is required for some installations, and insufficient for challenging environments and extensive feature utilization.

The following values are based on concurrent sessions:

Memory (RAM)
Up to 100              2GB
100 to 500             4 GB
500 to 1000           8 GB
1000 or more    16GB

Minimum Processor
Up to 500              2 dedicated CPU cores
500 to 1000           4 dedicated CPU cores
1000 or more         8 dedicated CPU cores

Storage
The application requires a minimum of 500 MB of storage space. Logging and Usage Tracking features can greatly increase this amount up to multiple gigabytes of storage space. Review of disc usage is recommended at regular intervals.

Software Requirements for the Linux Server

• Operating System :   Red Hat, Ubuntu, SuSE, CentOS, Mandrake, Caldera, Debian and other current Linux distributions.
• Java Runtime :         JRE 1.8 for full use of product features. Recommended Eclipse OpenJ9. A runtime is included with StayLinked Server v15.1 and newer for Linux systems.
• User Authority :         Root access is not required to install StayLinked. A user profile can be created to both run and manage the server file structure.

Administrator PC Requirements

Any modern Windows system should easily provide adequate resources for use of the StayLinked Administrator. The Administrator does not need to be running or active for operation of clients. It is strictly a user interface for configuration and visibility of sessions operating on the StayLinked Server.

Hardware Requirements for the Administrator PC

• 200 MB Hard Disk Space (additional required when gathering log files as needed.)
• Network Interface

Software Recommendations for the Administrator PC

• Windows 8.1 or newer
• Windows 2012 Server or newer
• UDP and TCP/IP access to the StayLinked Server
• Read/Write/Execute permissions to StayLinked Administrator objects for Windows user

Network Requirements

Wireless Network

• Wireless Access Points – These devices must be active, functional and have IP access to the StayLinked Server machine.
• Wireless RF Devices – These devices must be configured for access to the Wireless Access Points and have IP access to the StayLinked Server machine.
• Wireless Network Security Infrastructure – StayLinked is compatible with virtually all Wireless Network Security implementations.

Linux Server TCP-IP Requirements

StayLinked requires that the Linux Server has UDP and TCP/IP active and functioning, and that the server has UDP and TCP/IP access to the network.

Installing/Upgrading StayLinked Software

This section describes the installation of the StayLinked Server and the StayLinked Administrator. For existing StayLinked Customers, this section also describes the steps required to upgrade your StayLinked Server and Administrator software to the latest version. All of the installation and upgrade packages are available for download from the StayLinked portal. Those StayLinked customers who have a current Maintenance Agreement in force are entitled to these StayLinked upgrade packages.

StayLinked Server Installation

This section walks you through the installation of the StayLinked Server application onto a Linux Server platform. Once you have completed the installation, you will be running the latest version of the StayLinked Server. No further updates or upgrades will be required.

Prepare for Installation

Before installing the software, you will need to be logged into the Linux server as root or root equivalent.

Select a Location for the StayLinked Server Software

The StayLinked Server software components are installed into the ‘stay-linked’ folder and subfolders. You must select a parent folder for the ‘stay-linked’ folder. A suggested parent folder for the ‘stay-linked’ folder is ‘/usr/bin’, but you may install into your preferred location.

Download the StayLinked Server Software

The StayLinked Server Software is packaged in a ZIP file that can be downloaded from the StayLinked portal site at http://www.staylinked.com/portal. After downloading the ZIP, extract the Server TAR file and the Install Shell Script so that they can be transferred to the selected parent folder on the Linux server.

Transfer the StayLinked Server Software to the Linux Server

Transfer the ‘staylinked_linux.tar’ and the ‘slinstall.sh’ files to the Linux Server and into the folder that you wish to be the parent of the ‘stay-linked’ folder. If you use FTP for the transfer, make sure to select Binary Transfer Mode (BIN) before sending the files to the server.

Running the Script to Install the StayLinked Server

Open a terminal window on the Linux machine. Change your working directory to the location of the ‘slinstall.sh’ script file. Install the server files using this command:

sh slinstall.sh

The StayLinked Server will be installed into ‘stay-linked’ folder below the current folder.

Verify the contents of the StayLinked Server folder structure

The installation process will create the following folder and file structure under the selected parent folder where the TAR and shell files were placed:

stay-linked/config/
stay-linked/devices/
stay-linked/files/
stay-linked/iq/
stay-linked/jre/
stay-linked/lib/
stay-linked/logs/
stay-linked/api.sh
stay-linked/Client.jar
stay-linked/License_DM.txt
stay-linked/License_SLtxt
stay-linked/License_Voice.txt
stay-linked/slrc.html
stay-linked/stay-linked.gif
stay-linked/strserver.sh

Setting the Owner, Group and Mode for the StayLinked Server

The StayLinked Server should be owned by and run as root. Ensure that root has Read/Write/Execute authority to the folders and files included in the ‘stay-linked’ folder structure.

In cases where it is not possible or desirable to run StayLinked as a root user, please ensure that the user that StayLinked is started and run with also has read/write/execute authority to the directory containing the StayLinked file structure.

These commands will configure the owner, group and mode:

chown –R root stay-linked
chgrp –R root stay-linked
chmod -R ug+rwx stay-linked

Administrator Installation

The StayLinked Administrator should be installed after the StayLinked Server installation has been successfully completed.

Installing the StayLinked Administrator onto a Windows PC

Log on to the network using the PC that is to be designated as the Administrator for StayLinked.

Download the StayLinked Administrator Setup ZIP package from the StayLinked Portal. Extract the SETUP.EXE file from the ZIP into a folder on the Windows PC. Launch the installer by executing this SETUP.EXE program on the Windows PC.

(The following screens should be similar to but not necessarily exactly what you will see.)

On the Welcome Screen, click the Next button.

Please read the three license agreements and, if you agree, click the I Agree buttons.

Setup provides the ability to specify an installation location for the StayLinked Administrator. When you have selected the location, click the Next button.

Setup provides the ability to specify the Start Menu folder in which StayLinked Administrator shortcuts will reside. When you are ready to proceed with the installation, click the Install button.

A progress screen will provide status information as the StayLinked Administrator is installed.

A completion screen will display when the StayLinked Administrator installation has finished. Click the Next button to continue. (You can right-click in the progress information box to copy the details to the clipboard. This information can be provided to StayLinked Technical Support if there are any difficulties with the installation of the Administrator onto your PC.)

A final installation completion confirmation screen is displayed. Click the Finish button and the installation of the StayLinked Administrator is completed.

Upgrading the StayLinked Server

If you were not already running the latest version of the StayLinked Server, we would recommend that you upgrade to the latest version. The upgrade procedure will preserve all of the server settings and device settings that you have previously configured.

StayLinked upgrades are installed using the Linux Server Upgrade files. The StayLinked Linux Upgrade can be downloaded from the StayLinked Portal site at http://www.staylinked.com/portal.

The StayLinked Server upgrade for Linux can be applied while the server is running, but the upgrade will not take effect until the StayLinked Server is restarted.

Prepare for the Upgrade

It is recommended that the ‘stay-linked’ folder and contents and subfolders and their contents be backed up before applying the upgrade.

To apply the upgrade, you must be logged into the Linux server as root or root equivalent.

Identify the location of the StayLinked Server Software

The StayLinked Server software components were installed into the ‘stay-linked’ folder and subfolders. You must locate the current parent folder of the ‘stay-linked’ folder in order to apply the upgrade. The upgrade TAR files must be placed into this parent folder of the ‘stay-linked’ folder.

Download the StayLinked Server Upgrade Software

The StayLinked Server Upgrade Software is packaged in a ZIP file that can be downloaded from the StayLinked portal site at http://www.staylinked.com/portal. After downloading the ZIP, extract the Server Upgrade TAR file and the Upgrade Shell Script so that they can be transferred to the parent folder of the ‘stay-linked’ folder on the Linux server.

Transfer the StayLinked Server Upgrade Files to the Linux Server

Transfer the ‘staylinked_linux_upgrade.tar’ and ‘slupgrade.sh’ files to the Linux Server and into the parent of the ‘stay-linked’ folder. If you use FTP for the transfer, make sure to select Binary Transfer Mode (BIN) before sending the TAR to the server.

Running the Script to Upgrade the StayLinked Server

Open a terminal window on the Linux machine. Change your working directory to the location of the ‘slupgrade’sh’ script file. Upgrade the server files using this command:

sh slupgrade.sh

The upgrade script will properly upgrade the StayLinked Server.

Updating the –classpath argument in your ‘strserver.sh’ Startup Script

The StayLinked Server supports both SSH and SSL secure telnet connections and Device Management, Administrator Management, Usage Tracking and iQ features. Depending upon the server build that you are upgrading from, in order to have access to these new features, you will need to modify your StayLinked Server Startup Script (strserver.sh) to include the new Java JAR files for these features. The upgrade provides a sample startup script (strserver_150.sh) that will contain the new –classpath argument. You can use this startup script as a sample for modifying your existing startup script, or just rename the new ‘strserver_150.sh’ startup script to be called ‘strserver.sh’ and become your new startup script. There is also a ‘upgrade_readme.txt’ file included in the upgrade ZIP file that describes this procedure.

Setting the Owner, Group and Mode for the StayLinked Server

The StayLinked Server should be owned by and run as root. Ensure that root has Read/Write/Execute authority to the folders and files included in the ‘stay-linked’ folder structure. These commands will configure the owner, group and mode:

chown –R root stay-linked
chgrp –R root stay-linked
chmod –R ug+rwx stay-linked

Upgrading the StayLinked Administrator

If you were not already running the latest version of the StayLinked Administrator, we would recommend that you upgrade to the latest version. The upgrade procedure will preserve all of the server list entries that you have previously configured.

StayLinked upgrades are installed using the StayLinked Administrator Upgrade program. The StayLinked Administrator Upgrade can be downloaded from the StayLinked Portal site at http://www.staylinked.com/portal.

After downloading the ZIP, extract the ‘UPDATE.EXE’ to a folder on the Administrator PC and run the update program from that location. It is recommended that the StayLinked Administrator Upgrade only be run while the StayLinked Administrator is NOT running. Once applied, the upgrade will take effect when the StayLinked Administrator is restarted.

Using StayLinked on the Linux Platform

This section describes the operation of the StayLinked Server on the Linux Platform. Operations include starting the server, ending the server, backing up the server configuration and tuning the server performance.

Starting the StayLinked Server

The StayLinked Administrator communicates with the StayLinked Server, so it is required that the StayLinked Server process be running before continuing. Starting the server now will enable you to acquire the server serial number that you will need in order to obtain your StayLinked License Key.

The ‘strserver.sh’ script is used to start the StayLinked Server. You may start the server as a foreground or background process. You may also setup the StayLinked Server to run as a Daemon. The StayLinked server must be running in order for your devices and the administrator to connect to the server.

Change to the 'stay-linked' folder and start the StayLinked Server using this command:

(This command must be run with the StayLinked installation directory as the current working directory in order to locate relative file locations within the script.)

nohup sh strserver.sh

You can use your preferred method for running the StayLinked Server as a background process.

We have included the file Linux_systemctl_Startup_Script.zip in the ./stay-linked folder that provides one way to run StayLinked as a service on Linux.

The 'strserver.sh' script will reference the supplied Eclipse OpenJ9 Java within the StayLinked installation subdirectories.

Once the StayLinked Server is running, you should start and connect the StayLinked Administrator. After the Administrator is connected, you will be able to view the Server Serial Number on the Administrator Main Dialog. Please note the Serial Number value. You will need to provide this value in order to have a License Key be generated for your server machine.

Ending the StayLinked Server

The StayLinked Administrator provides a ‘Terminate Server’ menu option from the ‘Manage Connections’ dialog. This is the preferred method to shut down the StayLinked server.

Alternately, you may KILL the StayLinked Server process.

Using either method, if there are any active emulation sessions running on the server when the StayLinked Server is ended, those sessions will be terminated. Connected devices that are awake and active during the shutdown process will be automatically returned to the StayLinked Main Menu on the device. Those connected devices that were asleep during the server shutdown will have different behaviors depending upon the status of the server. If the StayLinked Server is running when the device is awaked, the device will display a ‘[Session Ended]’ message. If the StayLinked Server is not running when the device is awaked, the device will display a ‘[Linking]’ message. In either case, press the appropriate key to return to the StayLinked Main Menu.

Automatically Starting the StayLinked Server

You can use your preferred method for running the StayLinked Server as a background process. Typical methods for starting the StayLinked Server process on system IPL is by adding entries to the ‘/etc/inittab’ and/or to the ‘/etc/rc#.d’ files. Normally, these entries will run the ‘strserver.sh’ script.

StayLinked now includes a service.staylink file to register StayLinked as a service using the systemctl command which modern Linux distributions support.

Following are the instructions contained in the Linux_systemctl_Startup_Script.zip archive which can be found inside the extracted 'stay-linked' directory.

Please note if you use the staylinked.service file, this file will contain the Java memory parameters instead of the strserver.sh script.

Modify the staylinked.service file's "WorkingDirectory" path to your StayLinked's installation directory.

Place the staylinked.service file in /etc/systemd/system/ location.  This file should have 664 permissions. You can change this by running the command chmod 664 staylinked.service

Run the following commands.

        systemctl daemon-reload

        systemctl enable staylinked.service

        systemctl start staylinked.service

The StayLinked server should now be running.  You can verify this by running the command:

ps -ef | grep stayroot@supstayl01:/app/install_files_archive/Linux systemctl Startup Script#

Server Backup and Restore

Following is a list of the StayLinked files and folders that should be included in your backup processing.

• /qibm/userdata/stay-linked/config/*.*
• /qibm/userdata/stay-linked/deploy/*.*
• /qibm/userdata/stay-linked/devices/*.*
• /qibm/userdata/stay-linked/manifests/*.*
• /qibm/userdata/stay-linked/images/*.*

Note that the contents of the devices directory cannot be copied or backed up while the server process is running. This directory includes the secure database of Administrator user accounts which is locked during use.

StayLinked maintains backup copies of each configuration XML document that are time-stamped and stored along with the master copies listed above. These backup copies of the configuration files are generated each time the StayLinked Administrator saves changes to one of the files. The StayLinked Server maintains ten backup copies for each configuration file. These backup copies will allow you to possibly recover a previous configuration of the server.