Configuring a Liberty JVM server

Configure the Liberty JVM server if you want to deploy Enterprise Java applications such as EJBs, JSP, JSF, and servlets.

If you are configuring a CMCI JVM server, see Setting up CMCI for instructions instead. The CMCI JVM server is a special type of Liberty JVM server that supports the CMCI APIs. It is not used for hosting applications.

If you want to use an alternative version of Liberty from the default CICS® Liberty one, see the details in Configure an alternative Liberty installation location.

Note: Review the Configuring security for CICS Liberty topic for more security-related Liberty configuration information.

About this task

You have two ways of configuring a Liberty JVM server:
Autoconfigure
CICS automatically creates and updates the configuration file for Liberty, server.xml, from templates that are supplied in the CICS installation directory. Autoconfigure gets you started quickly with a minimal set of configuration values in Liberty. To enable autoconfigure, set the JVM system property, -Dcom.ibm.cics.jvmserver.wlp.autoconfigure property to true. If you are defining the JVM server in a CICS bundle, set this option.

Setting -Dcom.ibm.cics.jvmserver.wlp.autoconfigure to true will instruct CICS to create and configure Liberty. CICS will:
  • Create a Liberty server if one doesn’t exist
  • Add the required CICS Liberty feature to server.xml
    • cicsts:core-1.0
  • Add the CICS Security feature to server.xml and a <safRegistry> element, if security is active (SEC=YES)
    • cicsts:security-1.0
    • <safRegistry enableFailover=“false”id=“saf”/>
  • Add the transportSecurity feature if an HTTPS port has been specified
    • transportSecurity-1.0
  • Sets the server host, httpPort and httpsPort values within the <httpEndpoint> element, if supplied in the JVM profile
    • <httpEndpoint host=“*” httpPort=“nnnnn” httpsPort=“mmmmm” id=“defaultHttpEndpoint”/>
When the -Dcom.ibm.cics.jvmserver.wlp.autoconfigure property is set to false, CICS will expect a configured server.xml to be present in WLP_USER_DIR/servers/defaultServer.
The default value for -Dcom.ibm.cics.jvmserver.wlp.autoconfigure, if omitted, is false.
Manually configuring
This configuration is the default setting. You supply the configuration files and all values. Manually configuring is appropriate where you want to remain in full control of the Liberty server configuration.

To define the JVM server, see How you can define CICS resources.

Procedure

  1. Create a JVMSERVER resource. If you want to create a JVMSERVER resource within a CICS bundle, see Artifacts that can be deployed in bundles.
    1. Specify a name for the JVM profile for the JVM server. On the JVMPROFILE attribute of JVMSERVER, specify a 1 - 8 character name. This name is used for the file name of the JVM profile, which is the file that holds the configuration options for the JVM server. You do not need to specify the file type, .jvmprofile, here.
    2. Specify the thread limit for the JVM server. On the THREADLIMIT attribute of the JVMSERVER, specify the maximum number of threads you want to allocate. The actual number of threads that are used depends on the workload that you run in the JVM server. To start with, you can accept the default value and tune the environment later. You can set up to 256 threads in a JVM server.
    3. Set the location for the JVM profile. The JVM profile must be in the directory that you specify on the system initialization parameter, JVMPROFILEDIR. For more information, see Setting the location for the JVM profiles.
  2. Create the JVM profile to define the configuration options for the JVM server. You can use the sample profile, DFHWLP.jvmprofile, as a basis. This profile contains a subset of options that are suitable for starting the JVM server. All options and values for the JVM profile are described in JVM profile validation and properties. Follow the coding rules, including those rules for the profile name, in Rules for coding profiles.
    1. Make the following changes to the sample profile:
      • Set JAVA_HOME to the location of your installed IBM Java™ SDK.
      • Set WORK_DIR to your choice of destination directory for messages, trace, and output from the JVM server.
      • Set WLP_INSTALL_DIR to &USSHOME;/wlp. You can also use an alternative Liberty location by setting a different path, see Configure an alternative Liberty installation location.
      • Set TZ to specify the time zone for timestamps on messages from the JVM server. An example for the United Kingdom is TZ=GMT0BST,M3.5.0,M10.4.0
      • Set -Dfile.encoding to ISO-8859-1, for example -Dfile.encoding=ISO-8859-1.
      • (Optional) Set CICS_WLP_MODE to choose the level of integration between CICS and Liberty.

      For more information about JVM server options, see Symbols used in the JVM profile.

    2. Save your changes to the JVM profile. The JVM profile must be saved in EBCDIC file encoding on UNIX System Services and the file type must be .jvmprofile.
  3. Create the Liberty server configuration.
    Manually creating JVM servers is appropriate when the configuration files need to be carefully controlled. For more information, see Manually creating a Liberty server and Manually tailoring server.xml.
    Important: You should use autoconfigure if you are defining the JVM server in a CICS bundle, as the server.xml configuration file cannot be included with the JVM profile in a CICS bundle.
  4. Install and enable the JVMSERVER resource.

Results

The JVMSERVER reads the JVM profile and initializes itself based on the provided settings. If autoconfigure is enabled and a Liberty server configuration does not exist, it is created. If autoconfigure is not enabled and you have no configuration, or the configuration is incorrect, the JVMSERVER becomes DISABLED and report an appropriate failure. On subsequent start up, the JVMSERVER uses the existing configuration and launch the Liberty server instance. When the JVMSERVER completes startup successfully, the JVMSERVER resource installs in the ENABLED state.

If an error occurs, for example, CICS is unable to find or read the JVM profile, the JVM server fails to initialize. The JVM server is installed in the DISABLED state and CICS issues error messages to the system log. See Troubleshooting Liberty JVM servers and Java web applications for help. To confirm that Liberty successfully started within your JVM server, consult the messages.log file in the WLP_USER_DIR output directory on zFS.

CAUTION:
Do not use the Liberty bin/server script to start or stop a Liberty server that is running in a JVM server.
Note: In CICS integrated-mode Liberty, the current number of threads that are indicated by the JVM server returns a positive value and can fluctuate even when no workload is running. This situation occurs because threads are pooled within Liberty for efficiency.

What to do next

  • Run the CICS Liberty default web application to verify that the Liberty JVM server is running by using the following URL: http://server:port/com.ibm.cics.wlp.defaultapp/. For more information, see Configuring the CICS Default Web Application.
  • Specify any directories that contain native C® dynamic link library (DLL) files, such as IBM® MQ. Middleware and tools that are supplied by IBM or by vendors might require DLL files to be added to the library path.
  • Add support for security. See Configuring security for CICS Liberty.
  • Install the Enterprise Java applications (EAR files, WAR files, and EBA files), as described in Deploying a Enterprise Java application in a CICS bundle to a Liberty JVM server.
  • Liberty bootstrap properties can be placed in the JVM profile to achieve the same effect as using a Liberty bootstrap.properties file.
  • By default, Liberty and OSGi caches are not cleared on start-up of the JVM server. If CICS maintenance was applied since the JVM server last restarted, then the --clean option is used internally as a one-time operation to ensure caches are cleaned. Later, if you encounter caching issues, or receive guidance from the IBM Service team to clean your server, this situation can be achieved by using one of two approaches:
    • Add -Dcom.ibm.cics.jvmserver.wlp.args=--clean to your JVM profile.
    • Add -Dorg.osgi.framework.storage.clean=onFirstInit to your JVM profile.

    In both cases, remove the option when the server starts to ensure that subsequent restarts are not impacted by performance.

  • By default, when Liberty is configured, two defaulted settings are applied but are not visible in server.xml. For more information, see CICS Liberty defaulted settings.
  • For more information about general Liberty setup, see Liberty overview.

Configure an alternative Liberty installation location

You might not want to use the default installation of CICS Liberty because you have an instance of Liberty already in use. This configuration is sometimes referenced as "Bring Your Own Liberty" or BYOL.

You can address this need by configuring WLP_INSTALL_DIR to use the defined directory path for your existing installation. For more information, see JVM server option WLP_INSTALL_DIR.