Manually tailoring server.xml

Rules for server configuration

Liberty allows customization of your server.xml. For more information, see Server configuration.

Configuring the HTTP endpoint

If you want web access to your application, update the httpEndpoint attribute with the hostname and port numbers you require.

Use port numbers that the CICS region can open, either exclusively or as a shared port.

TLS must be configured to enable HTTPS. For more information, see Configuring confidentiality and integrity.

An HTTPS port must be configured to use the CICS default web application (cicsts:defaultApp-1.0).

<httpEndpoint host="zos.example.com" httpPort="9080" httpsPort="9443"
    id="defaultHttpEndpoint"/>

For more information, see Liberty overview.

Referencing environment variables in server.xml

Within server.xml, you can access and reference existing environment variables. See Using variables in configuration files.

The variables that can be referenced in server.xml can include custom environment variables that you set in a JVM profile. See Options for JVMs in a CICS environment.

Adding features

You must add one of the following features to the featureManager element.

• The CICS core feature cicsts:core-1.0 must be installed to start a CICS integrated-mode Liberty JVM server. The cicsts:core-1.0 feature integrates the Liberty server with CICS and provides access to CICS resources. The cicsts:core-1.0 feature provides the JCICS and JCICSX API to applications.
• The CICS standard-mode feature cicsts:standard-1.0 must be installed to start a CICS standard-mode Liberty JVM server. The cicsts:standard-1.0 feature does not have access to CICS resources by default. For more information, see CICS standard-mode Liberty: Java EE Full Platform support without full CICS integration.

You can add any of the Liberty features supported by CICS. For more information, see Liberty features.

CICS provides several features that can be added to a Liberty JVM server.

• The CICS security feature cicsts:security-1.0 integrates CICS security with the Liberty framework. cicsts:security-1.0 Is installed when CICS external security is enabled (SEC=YES in the SIT). Configure a user registry to use cicsts:security-1.0. For more information, see SAF user registry.
• The CICS distributed identity mapping feature cicsts:distributedIdentity-1.0 enables mapping distributed identities to SAF users.
• The CICS link feature cicsts:link-1.0 enables CICS to link to Java™ applications in the Liberty JVM server. For more information, see Linking to Java applications in a Liberty JVM server by using the @CICSProgram annotation
• The CICS JDBC feature cicsts:jdbc-1.0 enables applications to access Db2 through the JDBC APIs (java.sql.DriverManager, javax.sql.DataSource, and other classes). For more information, see Configuring database connectivity with JDBC
• The CICS default web application feature cicsts:defaultApp-1.0 enables the configuration service that validates the Liberty JVM server starts. For more information, see CICS default web application.
• The JCICSX remote development feature cicsts:jcicsxServer-1.0 enables a server that can receive remote requests from Java applications that use JCICSX API classes. For nor information, seeJava development using JCICSX.

<featureManager>
    <feature>cicsts:core-1.0</feature>
    <feature>cicsts:security-1.0</feature>
    <feature>cicsts:jdbc-1.0</feature>
</featureManager>

CICS bundle deployed applications

<include location="${server.config.dir}/installedApps.xml"/>

Including other configuration files

To maintain your Liberty server configuration, you can split it into multiple files. The include element is used to include other configuration files in server.xml. The LIBERTY_INCLUDE_XML JVM profile option is used to automatically add include elements to the server.xml file in CICS.

<include location="/path/to/include/file.xml" />

LIBERTY_INCLUDE_XML=/path/to/include/file.xml

For more information about including configuration files in Liberty, see Using include elements in configuration files.

For more information about the LIBERTY_INCLUDE_XML JVM profile option, see Options for JVMs in a CICS environment.

Bundle repository

<bundleRepository> 
    <fileset dir="/path/to/repository" include="*.jar"/>
</bundleRepository>

Global or shared library

A library element is used to share common JAR files between web applications. A global library shares JAR files with all web applications on the Liberty server. A shared library is added to the class path of the applications that depend on the JAR files.

<library id="global">
    <fileset dir="/path/to/library" include="*.jar"/>
</library>

OSGi applications in an EBA must use a bundle repository and cannot access JAR files in libraries. For more information, see Providing global libraries for all Enterprise Java applications or Shared libraries.

Liberty server application and configuration update monitoring

Liberty scans the server.xml file and included files for updates. By default, it polls for file changes every 500 milliseconds. To vary this value, configure a config element and set the monitorInterval attribute. The CICS server.xml template and auto configure processing set the monitorInterval to 5 seconds.

The applicationMonitor element configures how Liberty monitors applications for updates. The CICS server.xml template and auto configure processing disable application monitoring.

The applicationMonitor element also configures how drop-in applications are processed. To stop drop-in applications from being processed, set the dropinsEnabled attribute to false.

<config monitorInterval="5s" updateTrigger="polled"/>
<applicationMonitor updateTrigger="disabled" dropinsEnabled="false"/>

For more information, see Controlling dynamic updates.

JTA transaction log

When the Java Transaction API (JTA) is used, the Liberty transaction manager stores its recoverable log files in the zFS filing system. The default location for the transaction logs is ${WLP_USER_DIR}/tranlog/. This location can be overridden by adding a transaction element to server.xml.

<transaction transactionLogDirectory="/u/cics/CICSPRD/DFHWLP/tranlog/"/>

CICS default web application

The CICS default web application is a configuration service that validates the Liberty JVM server starts. To make the application available, make sure that the JVM profile option com.ibm.cics.jvmserver.wlp.defaultapp is set to true in your JVM profile.

Alternatively, remove the property from the JVM profile and add the cicsts:defaultApp-1.0 feature directly to server.xml.

An HTTPS port is required. Call the URL https://server:httpsPort/com.ibm.cics.wlp.defaultapp/ to run the application.

<server>
    <featureManager>
        <feature>cicsts:code-1.0</feature>
        <feature>cicsts:defaultApp-1.0</feature>
    </featureManager>

    <httpEndpoint httpPort="9080" httpsPort="9443" host="zos.example.com" />
</server>

SAF user registry

Define a SAF registry to use the CICS security feature unless you are mapping distributed identities to SAF users.

<safRegistry enableFailover="false" id="saf" />

For more information, see Configuring Liberty to use a SAF user registry.

CICS JTA integration

If an XA transaction is used by Liberty, the CICS unit-of-work becomes subordinate to the XA transaction by default. You can opt out of this automatic integration of CICS with JTA by setting the JVM profile option com.ibm.cics.jvmserver.wlp.jta.integration=false. Alternatively you can manually set the cicsts_jta element directly in your server.xml.

<cicsts_jta integration="false"/>

Modifying Lightweight Third-Party Authentication (LTPA) support

LTPA is configured by default when security is enabled for Liberty servers. LTPA enables web users to reuse their logged-in credentials across different applications or servers, with tokens signed by keys owned by the Liberty server.

In secure deployment scenarios, modify the default password for the LTPA keys file to protect server security. You can also modify the expiry interval of the tokens, and change the default file location. The file location must be modified to share keys between multiple Liberty servers.

Configuring CDI bean scanning

Applications that use Context and Dependency Injection (CDI) are scanned for CDI beans when the application is started. Scanning for CDI beans on all applications, including applications that don't use CDI, increases startup time.

The CICS server.xml template configures Liberty to not scan applications for CDI beans, unless they are defined as explicit bean archives. Explicit bean archives are defined by using a beans.xml file in the META-INF directory of a .jar files or in the WEB-INF directory of a .war files. The beans.xml file can be empty, or it can contain XML content that is defined by the CDI specification.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="https://jakarta.ee/xml/ns/jakartaee"
    xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/beans_4_0.xsd"
    version="4.0"
    bean-discovery-mode="annotated">
</beans>

The cdi element is used to configure the behavior of CDI in Liberty.

<cdi enableImplicitBeanArchives="false"/>

For more information, see Administering Contexts and Dependency Injection applications on Liberty.