Java VM and Wrapper (fs-wrapper*.conf)

Tanuki Java Service Wrapper

The Tanuki Java Service Wrapper envelops the FirstSpirit Java virtual machine (VM). The Java VM can be started and terminated using the wrapper.

Controlling

The wrapper is started and stopped using the fs-server (Unix) or fs-server.bat (Windows) control file:

• Controlling the server (Windows)
• Controlling the server (Unix)

Logging

The wrapper regularly checks the accessibility of the FirstSpirit Java VM during the runtime of the FirstSpirit process and records anomalies relating to the Java VM in a separate log file (fs-wrapper.log).

Both longer waiting times on the Java VM and outputs which would be made on the console by the Java VM, e.g., the outputs which are issued until the initialization of the LoggingManager when the FirstSpirit Server is started up, are recorded here.

Updating the wrapper

Crownpeak updates the wrapper intermittently. There may be several reasons for an update, such as:

• correcting errors in the wrapper
• security updates
• support for new Java versions
• support for changes to the operating system

We recommend updating the “Java Service Wrapper” promptly in the existing FirstSpirit installation.

You can find the version of the Tanuki Service Wrapper currently being used on the server via the FirstSpirit ServerMonitoring function. The “Wrapper version” is displayed under “Basic information (system)”, which can be found in ServerMonitoring – Overview – Status.

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 wrapper should be updated in line with the “Updating FirstSpirit (→Installation Instructions)”.

Updating a FirstSpirit Server by replacing the fs-isolated-server.jar file does not update the wrapper being used.

Before updating the wrapper the FirstSpirit server must be stopped. Any client connections to the server should be terminated before the wrapper is updated and the server is stopped to prevent any loss of data. Maintenance mode can be used to do this.

Configuration

Configuration files

The FirstSpirit Server conf subdirectory contains files which in turn contain important configuration settings for server startup and the FirstSpirit Server's Java system. These configuration files are responsible for starting and stopping the Java process and contain parameters which enable the optimum utilization of the main memory of the host operating system.

The following files may be available:

• the fs-wrapper-vendor.conf
  contains the recommended vendor startup options.
• the conf/fs-wrapper.conf file
  only contains the startup options that should be adjusted server specific.
  (configuration of the Java VM for non-isolated installations)
• the conf/fs-wrapper.isolated.conf file
  only contains the startup options that should be adjusted server specific.
  (configuration of the Java VM for isolated installations)
• the conf/fs-wrapper.slave.conf file
  (general configuration of the Java VM for cluster nodes for non-isolated installations)
• the fs-wrapper.isolated.slave.conf
  (general configuration of the Java VM for cluster nodes for isolated installations)
• the conf/fs-wrapper-j1.include.conf file
  (configuration of special start parameters for Oracle Java 8)
  (obsolete after changeover to new configuration)
• the conf/fs-wrapper-j2.include.conf file
  (configuration of special start parameters for Oracle Java versions >= 9)
  (obsolete after changeover to new configuration)

Some files are only relevant to use with certain Java versions (see Dependence on Java version).

The configuration file fs-wrapper-vendor.conf is part of the FirstSpirit update archive fs-update-[version].tar.gz. When updating the FirstSpirit server via the update archive fs-update-[version].tar.gz the startup options are automatically updated. Thus, the configuration adjustments are also available for existing FirstSpirit installations without any manual adjustments (and without overwriting the server-specific adjusted values by an update).
For further documentation see Updating FirstSpirit (→Installation Instructions)

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

For information about supported Java versions, see Technical requirements and recommendations and FirstSpirit release notes.

Default configuration

On installation, the files initially contain a default configuration specified by Crownpeak that is designed for maximum compatibility with many FirstSpirit installations. These should be optimized according to the needs and requirements of productive customer installations, however. Java experts, consultants from partner companies, or Crownpeak should be consulted for advice in this regard.

You can find a complete description of all parameters and more information at:
http://wrapper.tanukisoftware.org/doc/english/properties.html.

Changing the configuration files

Changes to these configuration files can be applied to some extent via the FirstSpirit ServerMonitoring function (see Startup options). The changes are then written to the configuration file and updated on the server. If invalid configuration settings are made, the error will be flagged up in ServerMonitoring when the configuration is saved and the save operation will not be completed:

unexpected configuration property key 'wrapper.startUp.timeout' in line 76

Alternatively, you can make changes to the configuration files directly on the files in the file system.

The order of the parameters is arbitrary.

Some parameters are explained using examples below.

• Configuring the Java VM
• Common Java parameters
• Java wrapper parameters
• Logging (log files)
• IPv6 support
• System service under Windows
• Other parameters

The server must be restarted after any changes to the configuration files.

Do not insert comments into a line with parameter values in the configuration files, e.g.: wrapper.startup.timeout=30 # Comment

Dependence on Java version

Some configuration settings for starting up the server depend on the Java version being used.

This means that the latest Java version supports different parameters to an older Java version and vice versa.

For information about version-dependent configuration, see Configuration subject to the (Java) version.