Manually tailoring server.xml

If you want to make manual changes to your server.xml, there are some basic configurations you can apply. Your CICS® region user ID needs to have both read and write access to the server.xml file.

Configuring the HTTP endpoint

If you want web access to your application, update the httpEndpoint attribute with the host name and port numbers you require. For example: 
<httpEndpoint host="winmvs2c.example.com" httpPort="28216" httpsPort="28217"
 id="defaultHttpEndpoint"/>

Use a port number that is not in use elsewhere, for example by a TCPIPSERVICE in CICS.

HTTPS is available only if SSL is configured (see Configuring SSL (TLS) for a Liberty JVM server using a Java keystore).

For more information, see Liberty profile overview in WebSphere Application Server v9 product documentation.

Adding features

Add the following features in the <featureManager> list of features.

  • CICS feature cicsts:core-1.0. This feature installs the CICS system OSGi bundles into the Liberty framework. This feature is required to start a CICS integrated-mode Liberty JVM server. You must also define a SAF registry.
  • CICS feature cicsts:standard-1.0. This feature is required 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 7 Full Platform support without full CICS integration.
    Note: Specify either the cicsts:core-1.0 or cicsts:standard-1.0 feature. You cannot specify both features in server.xml.
  • CICS security feature cicsts:security-1.0. This feature installs the CICS system OSGi bundles that are required for CICS Liberty security into the Liberty framework. This feature is required when CICS external security is enabled (SEC=YES in the SIT) and you want security in the Liberty server. To use the cicsts:security-1.0 feature, you must also configure a user registry. For more information, see the user registry section in this topic.
  • jsp-2.3. This feature enables support for servlet and JavaServer Pages (JSP) applications. This feature is required by Dynamic Web Projects (WAR files) and OSGi Application Projects containing OSGi Bundle Projects with Web Support that are installed as CICS bundles.
  • cicsts:jdbc-1.0. This feature enables applications to access DB2 through the JDBC DriverManager or DataSource interfaces.
Example:
<featureManager>
    <feature>cicsts:core-1.0</feature>
    <feature>cicsts:security-1.0</feature>
    <feature>jsp-2.3</feature>
    <feature>cicsts:jdbc-1.0</feature>
</featureManager>
For more information, see Liberty features.

CICS bundle deployed applications

If you want to deploy Liberty applications that use CICS bundles, the server.xml file must include the entry:
<include location="${server.output.dir}/installedApps.xml"/>
The included file is used to define CICS bundle deployed applications.

Bundle repository

Share common OSGi bundles by placing them in a directory and referring to that directory in a bundleRepository element. For example:
<bundleRepository> 
    <fileset dir="directory_path" include="*.jar"/>
</bundleRepository>

Global/shared library

Share common JAR files between web applications by placing them in a directory and referring to that directory in a global/shared library definition. 
<library id="global">
    <fileset dir="directory_path" include="*.jar"/>
</library>
The global/shared libraries cannot be used by OSGi applications in an EBA, which must use a bundle repository. For more information, see Providing global libraries for all Java EE applications in WebSphere Application Server for z/OS product documentation or Liberty: Shared libraries .

Liberty server application and configuration update monitoring

The Liberty JVM server scans the server.xml file for updates. By default, it scans every 500 milliseconds. To vary this value, add an entry such as:
<config monitorInterval="5s" updateTrigger="polled"/>

It also scans the dropins directory to detect the addition, update, or removal of applications. If you install your web applications in CICS bundles, disable the dropins directory as follows:

<applicationMonitor updateTrigger="disabled" dropins="dropins" dropinsEnabled="false" pollingRate="5s"/>.

JTA transaction log

When it uses the Java Transaction API (JTA), 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 such as 
<transaction transactionLogDirectory="/u/cics/CICSPRD/DFHWLP/tranlog/"/>

CICS default web application

The CICS default web application CICSDefaultApp is a configuration service that validates the Liberty JVM server has started. To make the application available add the JVM profile option com.ibm.cics.jvmserver.wlp.defaultapp=true to your JVM profile, or if you are not using autoconfigure, you can manually add or remove the cicsts:defaultApp-1.0 feature from your server.xml. Run the application by using the URL http://<server>:<port>/com.ibm.cics.wlp.defaultapp/.

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

User registry

Unless you are using distributed identity mapping, you must define a SAF registry to use the CICS security feature:
<safRegistry id="saf"/>
For more information, see Configuring security for a Liberty JVM server by using distributed identity mapping or Liberty profile: Configuration elements of DataSources in WebSphere Application Server for z/OS product documentation.

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=true. If you are not using autoconfigure, you can manually set the element in your server.xml: <cicsts_jta Integration="true"/>.

Modifying Lightweight Third-Party Authentication (LTPA) support

LTPA is configured by default when security is enabled for Liberty servers. LTPA enables web users to re-use their logged-in credentials across different applications or servers, using tokens signed by keys owned by the Liberty server. In secure deployment scenarios, you should 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, which is required if sharing keys between multiple Liberty servers.