Configuration subject to the (Java) version

Transferring parameters to the Java VM subject to the (Java) version

With each new version of Java, new start parameters are supported, while other parameters are omitted. The configuration settings for the server startup are therefore also always dependent on the Java version used.

Before switching to a new version of Java, the Java VM start parameters should be checked and adapted where necessary, as it is not possible to start the Java VM with outdated parameters (see Migration).

In FirstSpirit, a configuration file containing a configuration for different versions of Java can be used to do this (recommended).

For older versions of the Tanuki Java Service Wrapper (< version 3.5.36), a version-dependent configuration involving additional include files fs-wrapper.isolated-j#.include.conf was possible (see Separate configuration files). In these cases, Crownpeak recommends updating the Java Service Wrapper to version >= 3.5.36 and a configuration changeover.

One configuration file for different Java versions (recommended)

Prerequisite

A Java Service Wrapper with version 3.5.36 or higher is required to use one configuration file for different Java versions:

• If you use the FirstSpirit update directory, you will always receive a current version of the wrapper (see Updating FirstSpirit (→Installation Instructions)).
• You can find the version of the Java Service Wrapper currently being used on the server via FirstSpirit ServerMonitoring. The “wrapper version” is displayed under “Basic information (system)”, which can be found in ServerMonitoring – Overview – State.
• If the wrapper version used does not correspond to the version recommended by the FirstSpirit Server, this is indicated by the red font and the term outdated. This is also recorded in the fs-wrapper.log file.
  In this case, the Java Service Wrapper should be updated promptly (see Updating the FirstSpirit backend).

Transferring parameters subject to the version

The Tanuki Java Service Wrapper allows you to transfer all start parameters into an individual configuration file by specifying additional parameters. However, these parameters are only evaluated for certain Java versions.

By specifying wrapper.java.additional.<n>.java_version.min or wrapper.java.additional.<n>.java_version.max, you can restrict the evaluation of Java-specific parameters to certain Java versions (see below).

Note on include files:

Additional include files fs-wrapper.isolated-j#.include.conf may be available in existing FirstSpirit installations. These files were introduced for Java 9, as the necessary start parameters were not compatible with the start parameters for version 8.

These old files can be deleted with the new configuration or after the configuration has been adapted.

Note on the fs-wrapper-vendor.conf configuration file:

The fs-wrapper-vendor.conf configuration file contains the recommended manufacturer start options for the Java VM and is part of the FirstSpirit fs-update-[version].tar.gz update archive. These parameters are important for starting the FirstSpirit Server properly and are monitored and kept up to date by Crownpeak Technology GmbH. For example, the parameters for garbage collection or timeout times are adapted to values which – in our experience – make sense for most FirstSpirit Servers.

The start options are updated automatically when the FirstSpirit Server is updated via the fs-update-[version].tar.gz update archive. Accordingly, these configuration modifications are also available for existing FirstSpirit installations without requiring manual adaptation.
For more information, see Updating FirstSpirit (→Installation Instructions).

The fs-wrapper-vendor.conf configuration file should not be modified. Should it be necessary to adapt the recommended manufacturer start options in isolated cases, the corresponding start parameters should be redefined in the fs-wrapper[.isolated].conf configuration file (and not overwritten in fs-wrapper-vendor.conf ).

Syntax (examples)

FirstSpirit can only be started with Java versions >=11:

wrapper.java.version.min=11  

This parameter is only used for Java version 11. It is ignored from Java version 12 onwards:

wrapper.java.additional.40=-XX:+UseConcMarkSweepGC 
wrapper.java.additional.40.java_version.max=11  

This parameter is only used for Java version >= 11. It is ignored for Java version 10:

wrapper.java.additional.60=--add-exports=java.base/sun.security.util=ALL-UNNAMED 
wrapper.java.additional.60.java_version.min=11  

This parameter is only used for Java version 11. It is ignored for all other Java versions:

wrapper.java.additional.65=--add-modules=java.activation 
wrapper.java.additional.65.java_version.min=11 
wrapper.java.additional.65.java_version.max=11  

Further information

You can find a complete description of the parameters and more information at:

https://wrapper.tanukisoftware.com/doc/english/prop-java-additional-n.html

Separate configuration files for different Java versions (outdated configuration)

Prior to the version-dependent configuration of parameters in one configuration file, it was also possible to establish a version-dependent configuration using different configuration files.

For this, the Java version being used is determined automatically. Depending on the result, different configuration files are evaluated, for example:

• the conf/fs-wrapper-j1.include.conf file (for Oracle Java 8) or
• the conf/fs-wrapper-j2.include.conf file (for Oracle Java versions >= 9)

In these cases, Crownpeak recommends updating the Java Service Wrapper to version >= 3.5.36 and a configuration changeover.

Migration

When is a changeover advisable?

We recommend adapting the existing configuration to the new parameters:

• after updating the Java Service Wrapper to version >= 3.5.36 and
• when using Java versions >= 9

How do you change over an existing configuration?

A default configuration specified by Crownpeak is provided with the new syntax during installation via the <FirstSpiritROOT>/conf/conf-all/fs-wrapper.conf.default.txt file. This default configuration can be used as the basis for the new configuration.

The default configuration of the Java Service Wrapper provided can differ from the configuration in specific customer installations. The specific parameters and values of the fs-wrapper.conf or fs-wrapper.isolated.conf files and the fs-wrapper-j#.include.conf include files must be applied to the new configuration and adapted to the new syntax (if they differ from the default configuration).

Ideally, the number of parameters applied should be kept to a minimum.

We recommend proceeding as follows:

• The <FirstSpiritROOT>/conf/conf-all/fs-wrapper.conf.default.txt file (or its isolated version) must be copied to the <FirstSpiritROOT>/conf/ directory.
• Apply the relevant parameters from the existing fs-wrapper.conf, particularly:
  • wrapper.java.maxmemory and wrapper.java.initmemory (use the higher value in the new file for both parameters)
  • possibly wrapper.java.command
  • parameters configured individually, which are required for operation.
• After amending, rename the old file (e.g., to fs-wrapper.conf.old) and then rename the new file to fs-wrapper.conf or fs-isolated-wrapper.conf.
• Start FirstSpirit.

Each time the start parameters are changed, the performance of the FirstSpirit Server must undergo a critical check in the following days.

Error analysis – FirstSpirit Server no longer starts: If the FirstSpirit Server no longer starts after the change, you must start by using the old fs-wrapper.conf again.

You can then carry out an error analysis using the /log/fs-wrapper.log log file (together with Technical Support if necessary) – see also Logging. In this log file, the wrapper records anomalies relating to the Java VM, e.g., longer waiting times on the Java VM, as well as outputs which would be made on the console by the Java VM (including the outputs which are issued until the initialization of the LoggingManager when the FirstSpirit Server is started up).