JVM Configuration

Each of the Curity Identity Server’s run-time nodes runs inside a separate instance of the Java Virtual Machine (JVM). This VM includes a number of options and flags that can severely impact performance. To configure these, like all other configuration of the Curity Identity Server, the configuration service’s API is used. The flags of the JVM are configured per service (i.e., per run-time node) from this central service. This is helpful for a few reasons:

  • In large deployment with dozens or hundreds of nodes, it is simple to manage all JVM settings from one place.
  • Each service (or cluster of services) can be configured differently. This allows some services to be tuned for throughput and others for latency. It also allows for debugging of the Garbage Collector (GC) to be enabled for some services (like those in a performance lab) and off for others (like production run-time services).

Configuration of a service’s JVM options is done by setting the property jvm-options of a service role. After this is set, the Curity Identity Server needs to be restarted for the changes to take effect. This is one of the few configuration changes in the Curity Identity Server that requires a manual restart of the service; all others are immediately and automatically applied.

Warning

These changes will not take effect on a server node’s first run unless the file $IDSVR_HOME/var/jvm-options is created and contains the same flags as configured. Without this file, the first run will use the default JVM settings, and changes will only take effect after the node has been restarted.

Changing JVM Settings in the Admin UI

To configure the JVM setting in the UI:

  1. Go to System ‣ Deployments
  2. Click the server node you want to modify or create a new one
  3. Click Show Advanced Settings
  4. Enter the JVM flags into the JVM Options input field and close the modal
  5. Commit the changes by selecting Commit from the changes menu in the top right corner

Changing JVM Settings with the REST API

To change the JVM settings, use the REST API as follows:

  1. In a shell or using a similar API client (e.g., Postman), make an HTTP PATCH request to add the JVM options. For instance, this can be done using curl like this:

    Listing 174 Changing the default JVM options
    $ SERVICE_ROLE=runtime
$ curl -k -u admin:Password1 -X PATCH -H "Content-Type: application/vnd.yang.data+xml" -d '
    <service>
        <jvm-options>-XX:+PrintGCDetails -XX:+UseG1GC</jvm-options>
    </service>
    ' "https://localhost:6749/admin/api/rest/running/environments/environment/services/service-role/$SERVICE_ROLE"

  2. Verify that the options was set correctly by making an HTTP get request like the following:

    Listing 175 Checking that the configuration was successfully updated
    $ curl -k -u admin:Password1 \
    "https://localhost:6749/admin/api/rest/running/environments/environment/services/service-role/$SERVICE_ROLE/jvm-options"

    This will return an XML element containing the configured valued, like this:

    Listing 176 An example of the configured JVM options returned from the REST API
    <jvm-options xmlns="https://curity.se/ns/conf/base" xmlns:y="http://tail-f.com/ns/rest" xmlns:base="https://curity.se/ns/conf/base">
    -XX:+PrintGCDetails -XX:+UseG1GC
</jvm-options>

  3. Restart the node to begin using this new configuration. This is the only configuration change in the Curity Identity Server that requires a restart of a node. Upon restart, the new JVM settings will be used.

Changing the JVM Settings with the CLI

This setting can also be updated using the Command Line Interface (CLI). To do this, follow these steps:

  1. Start the CLI by starting idsh.

  2. Enter configuration mode by typing configure and hit enter.

  3. Type the following and press enter:

    Listing 177 Setting the JVM options in the configuration mode of the CLI
    set environments environment services service TestServer1 jvm-options "-XX:+PrintGCDetails -XX:+UseG1GC"

    Tip

    Be sure to include the arguments in quotes.

  4. Commit the transaction by typing commit and pressing enter.