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 efficiently. 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 with Java JRE version 15 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 19

The QPE uses virtual threads when available. They were introduced in Java 19 as the Preview feature. Therefore, if you choose to use Java 19, you will need to add the --enable-preview option to your JVM parameters in /usr/share/tomcat9/bin/setenv.sh.

Java 15

When you have Java 15 available, 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"

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.

Java 8

If Java 15 is not available in your environment, QPE requires at least Java 8. On those systems, G1GC (-XX:+UseG1GC) is the next best option for the garbage collector.

With Java 8, you might specify:

export CATALINA_OPTS="-Xmx4g -XX:+UseG1GC -Djava.awt.headless=true -Dproject.folder=/opt/quuppa/PE"

Some parameters work also fine if added as export CATALINA_OPTS=".." -line. In Windows you may need to use the graphical user interface of Tomcat server to define these parameters.

Table 1. Available JVM Startup Parameters
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:+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	Deprecated. 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	Optional. Allows defining the number of threads the QPE will use. The number is number of threads reserved for actual positioning calculation relative to number of CPU cores in the system. Typical value would be -1 for system with around 4 cores, -2 for bigger setups with 10 cores or more.
-DsimulatorMode	-DsimulatorMode	Optional. Starts QPE in simulator mode, ready to receive simulated data from QSP. Project file is transmitted from QSP.