StayLinked installations vary in size from one session to thousands on a single machine. This document aims to describe some of the more common system parameters that can impose session limitations or impact performance. It is critical that your server hardware appropriately represents the number of users that depend on this system and use of advanced product features.
Machine Sizing and Resources / Minimum System Requirements
In a basic configuration, the resource requirements are minimal. Our server installation guides offer system requirements for the most common environments and platforms.
StayLinked will work on pretty much any modern Windows, Linux, Unix, and IBMi system. As a telnet client, a single StayLinked Server can provide connections to any number of telnet hosts and multiple emulation types. The resources required will depend on a several variables including, but not limited to:
- Type of emulation and security.
- Rate of user activity.
- Version and configuration of the Java runtime used to operate the StayLinked server process.
- Efficiency of screen updates from the hosted application(s).
- Quantity and usage of StayLinked advanced features.
- Availability of system resources.
- Expected Growth
For larger installations, the best practice is to monitor your actual utilization since it is the only way to measure performance within your environment. Once you reach about 50 active users, any additional seats should scale in a linear fashion. We typically recommend that all customers review this guide at about 50 active sessions though the variables listed above can impose limitations at any number of active sessions.
Java Memory Allocation
Making sure that enough memory (heap) is available is important to every StayLinked Server. If no memory arguments are provided, the system will use Java default values when creating the JVM. Older JVMs will default to an Xmx value of 512MB, 1GB, or a percentage of hardware memory on the machine. Older StayLinked startup scripts are set to 1 or 2 GB depending on the version. The current version of StayLinked for Windows and Linux includes OpenJ9, does not set an Xmx value explicilty and thus uses the JVM default Xmx value as follows…
- The value is 25% of the available memory with a maximum of 25 GB. However, where there is 2 GB or less of physical memory, the value set is 50% of available memory with a minimum value of 16 MB and a maximum value of 512 MB. (Retrieved from the Notes section of https://www.eclipse.org/openj9/docs/openj9_defaults/ on Feb 17, 2022.)
- IBM i is not listed above and uses a default Xmx of 2 GB.
- IBM J9 JVMs before 2020 will use 50% of available memory with a minimum value of 16 MB and a maximum value of 512 MB.
Typical installations will use roughly 50MB plus 1 MB per active connection. This could increase to 10MB or more per connection with the use of advanced features like Screen Recognition and extensive graphical design. Memory requirements can sometimes be significantly lower, but the range of telnet application design and variables makes it impossible to reproduce or accurately estimate any individual production environment.
The JVM Current heap size provides a metric for tuning the Java parameters entered in the startup script or Windows Service description. In regular operation, the JVM Current Heap size will grow and shrink as needed. On Windows systems that are not configured with a startup size, this value can start high and shrink over time. Reviewing these values during peak hours of operation can provide an estimate of the upper limit required under those conditions. Memory use is regularly recorded in the StayLinkedManager.log file:
DATE | TIME – JVM Current Heap Size: 61535k, Heap Memory Used: 55405k (90%), Free Heap Memory: 6129k (9%)
IBMi (aka AS/400, iSeries), Linux and Unix installations use arguments in the strserver.sh startup script.
-Xms<memory>m indicates the minimum memory allocation
-Xmx<memory>m represents the maximum memory allocation
The trailing m represents megabytes which can also be entered as a g for giabytes. A sample script would look something like this:
/usr/java/bin/java -Xms256m -Xmx2048m -classpath lib/staylinked.jar:lib/s……. <snip>
This picture shows an example of an AIX machine with an older JVM crashing at 512 MB. The Blue line is the Heap Size (growing until it reaches the Xmx), and the Orange is the Heap in Use. When the Heap in Use after a Major Garbage Collection grows to reach the Xmx, the server will crash.
Windows Servers provide these arguments as part of the StayLinked Server Service.
- Server versions build 146 and older include these memory arguments in the installstaylinked.bat file. If changes are made to the installstaylinked.bat file, you must run the uninstallstaylinked.bat to remove the existing service and then run the file installstaylinked.bat to reinstall the service with the new parameters. Significant enterprise-level enhancements have been made that can greatly improve performance over these older versions. Upgrading a server of this age is always recommended whenever possible.
- Server versions build 147 to 210 will pull these values during the Server startup from the contents of a StayLinkedService.ini file in the StayLinked Server installation directory.
- Server versions build 212 and newer no longer start with Xmx values. Instead the server will set the Xmx based on the system RAM as described above. Xmx values can be added if needed, but they will be lost if StayLinked is upgraded. We recommend adding more RAM to the system if a higher Xmx is needed.
Heap Sizing Recommendations
Installations using the recommended OpenJ9 runtime should follow IBM guidelines for memory configuration. Xmx should be set so that memory used by live objects, or the amount of memory after a Major Garbage Collection (GC) cycle (The bottom of the jagged Orange line in the graph above) is 40 to 70% of the Xmx value. For example, if the amount of RAM used in the Java heap after Major CG cycles changes through the day from 600 MB to 1 GB, then recommended Xmx configuration would be 1.5 GB for optimal performance. More information on this can be found in IBM’s J9 VM Reference section on “How to do Heap Sizing” on page 58.
More information regarding the server startup process can be found in the respective installation guides for each server platform.
IBM iSeries Fixed Private Pool
For larger installations on IBM iSeries systems, we recommend creating a fixed private pool for the StayLinked resources. In some cases, operating in *BASE can result in a shortage of resources that can have various negative effects on the StayLinked Server Process. The following steps can be used to create the fixed private pool. These values can be easily adjusted downward, but the Server may be interrupted if too few resources are allocated. You can always make adjustments after monitoring of actual RAM and thread usage during peak production periods. The following example includes details for pool number 2 with up to 500MB and 2000 threads. Please contact StayLinked Support for assistance in recommended resources for your installation.
1) Change the STAYLINKED subsystem description to add a Fixed Private Storage Pool of 500MB with 2000 Max Active processes.
CHGSBSD SBSD(STAYLINKED/STAYLINKED) POOLS((1 *BASE) (2 512000 2000))
2) Modify the STAYLINKED subsystem routing entries so that all jobs in the STAYLINKED subsystem use pool ID 2.
CHGRTGE SBSD(STAYLINKED/STAYLINKED) SEQNBR(9999) CMPVAL(*ANY) POOLID(2)
Once these changes are made to the subsystem description, they will not take effect until the StayLinked Server process is restarted. Restarting the Server process will end all active sessions, and should typically be scheduled to reduce user interruption.
The STAYLINKED subsystem can be ended with the following command:
ENDSBS SBS(STAYLINKED) OPTION(*IMMED)
Once ended, the Server can be started up with the following command:
STAYLINKED/STRSERVER
Once the STAYLINKED subsystem is back up and running, use WRKSYSSTS to verify that StayLinked is running in a private fixed pool.
Lastly, The WRKACTJOB SBS(STAYLINKED) command can be used to review the pool information and number of active threads by using F11 to cycle through job information. The Pool column for the 4 jobs will match the System Pool column from WRKSYSSTS.
Changes to the startup scripts will only take affect during the startup of the Server process.
Additional Tuning Articles are available below:
CPU Time
Telnet Source Address and per_source
Threads per Process
Open Files
Hard Disk Space and File Management
Tuning Virtualized Servers
Known Issues Related to VM Performance and Tuning
Share the post "Server Tuning Guide – Parameters"