Java Virtual Machine Startup Parameters
Setting Java Virtual Machine Startup Parameters
Starting Quuppa Positioning Engine (QPE) correctly requires some Java Virtual Machine (JVM) startup parameters to be set. Quuppa highly recommends using the latest Java versions to run the system optimally. As a system dealing with real-time data, QPE is sensitive to any process interruptions, e.g. "stop-the-world" execution cycle of the JVM garbage collector. Quuppa currently recommends running all systems at least with Java JRE version 17 or above with its production ready ZGC garbage collector that is specifically designed for real-time application in mind and for efficiently handling gigabytes of memory.
In Ubuntu system using Tomcat 9 as application container, JVM parameters are typically set in file /usr/share/tomcat9/bin/setenv.sh. Create one if this configuration file doesn't exist yet. For more information, see the QPE Installation instructions.
Java 21 (recommended)
Java version 21 introduced several features that QPE can benefit from. Java 21 includes a production ready Generational ZGC garbage collector which can significantly reduce memory footprint and latencies, and in general improves system performance and efficiency. Java 21 also supports virtual threads that QPE will use for improved performance.
When using Java 21, add/modify the line export CATALINA_OPTS=".." in the file to specify the required parameters, for example:
export CATALINA_OPTS="-XX:+UseZGC -XX:+ZGenerational -XX:MaxRAMPercentage=70
-XX:-ZUncommit -Djava.awt.headless=true
-Dproject.folder=/opt/quuppa/PE"Java 17 (minimum recommended)
When using Java 17 or above, add/modify the line export CATALINA_OPTS=".." in the file to specify the required parameters, for example:
export CATALINA_OPTS="-XX:+UseZGC -XX:MaxRAMPercentage=70 -XX:-ZUncommit -Djava.awt.headless=true -Dproject.folder=/opt/quuppa/PE"Java 16 and below (deprecated)
Different options are supported in different versions of JVM. Refer to the table below for recommended options with ZGC and to ZGC documentation for other supported options.| Parameter Name | Example | Description |
|---|---|---|
| -XX:+UseZGC | -XX:+UseZGC | Optional. Tells JVM to use ZGC as the garbage collector. ZGC requires at least Java version 15. |
| -XX:+ZGenerational | -XX:+ZGenerational | Optional. Enables Generational ZGC. Requires -XX:+UseZGC to be defined also. Requires Java version 21. |
| -XX:+UseG1GC | -XX:+UseG1GC | Optional. Tells JVM to use G1 garbage collector. Use if Java 15 is not available. |
| -XX:MaxRAMPercentage | -XX:MaxRAMPercentage=70 |
Optional. Requires at least Java 10. Sets the maximum RAM usage (in percentage of what's available in the system) for the JVM process. If you use this relative setting, 70 is Quuppa's current default recommendation. Do not set it too high as it may lead to a system crash, especially in a busy system when the available memory becomes fragmented and the OS is not anymore able to allocate a new memory JRE requests. |
| -Xmx | -Xmx4g | Optional. Maximum amount of memory that JVM can allocate for QPE, example allocates 4 GB which is enough for moderate sized projects. Only specify this or the relative maximum with MaxRAMPercentage but not both. |
| -XX:-ZUncommit | -XX:-ZUncommit | Optional. Requires at least Java 13. Means that JRE will not give memory back to the OS even when it doesn't need it. It will show up as continuously high memory usage but in a dedicated system that doesn't matter and it will help reduce memory fragmentation as the JRE is in the charge of managing memory for its needs. |
| -Djava.awt.headless=true | -Djava.awt.headless=true | Required. |
| -Dproject.folder | -Dproject.folder=/opt/quuppa/PE | Required. Tells QPE in which folder project files are stored. Do not store any additional files in this folder as the system will wipe this folder clean when communicating with the Quuppa Customer Portal. Also you do not need to manually add any files to the folder, QPE does that automatically when communicating with QCP. |
| -DallowLocatorsFromAnySubnet | -DallowLocatorsFromAnySubnet | Obsolete. This parameter is no longer needed when using DHCP options or having Locators in multiple subnets. By default, QPE will allow Locators to connect from any subnet or IP address. |
| -DlocatorNetworkInterface | -DlocatorNetworkInterface=192.168.123.124 | Optional.Enables QPE to monitor the status of the right network interface(s) in case Locators are not in the same subnet with the QPE, i.e. when using DHCP options, or when multiple local subnets are used. -DlocatorNetworkInterface contains the local IP address(es) of the network interface(s) that are used to connect to the Locators. When defining multiple network interfaces, IP addresses are separated by commas. |
| -DuseMovedLocators | -DuseMovedLocators | Optional. If this parameter is set, moved Locators are used in positioning. Otherwise they are commanded to deployment mode. |
| -DuseThreadPool | -DuseThreadPool=-2 | Obsolete. This parameter is no longer needed as QPE handles threads automatically and dynamically. |
| -DsimulatorMode | -DsimulatorMode | Optional. Starts QPE in simulator mode, ready to receive simulated data from QSP. Project file is transmitted from QSP. |
| -DdoNotConnectToQCP | -DdoNotConnectToQCP | Optional. When set, QPE does not try to connect automatically to QCP for sending status updates and performing project file and subscription sync. Use only with offline project with a subscription that has offline module enabled. |