Defining a client allowlist to CMCI JVM server in a CICSplex
You can use a client allowlist to limit clients that can connect to the CMCI JVM server. For example, you can limit
which levels of CICS Explorer® or a browser can
connect to the CMCI JVM server.
Note: This capability allows you to manage clients that are allowed to connect to the CMCI, but do
not expect this to secure the CMCI.
The client allowlist is an ASCII file that contains a list of valid User-agent HTTP headers that
are sent by a client such as CICS Explorer or
a browser.
You use the com.ibm.cics.jvmserver.cmci.user.agent.allow.list JVM property
to specify the location to the allowlist file. If the property is not defined in the JVM profile of
the CMCI JVM server, all clients are
accepted.
If a user-agent is not in the file, the request is rejected with HTTP code 403, and message
DFHSJ1412 is issued. You can specify an alternative response text to return to the
user by using the
com.ibm.cics.jvmserver.cmci.user.agent.allow.list.reject.text JVM property.
Note: The CICS Explorer user-agent encodes the
versions of several CICS Explorer components
and therefore can change when components are updated. With IBM® CICS Explorer for Aqua 3.1 (Fix Pack
5.4.0.5) or later, you can discover the user-agent that a running CICS Explorer installation presents by clicking Help > About > Installation Details > Configuration. The CMCI User Agent string is listed in the Configuration tab
of the Installation Details dialog box. (Aqua refers to IBM Explorer for z/OS® Aqua.)
Procedure
Define a client allowlist file.
In the file, you can use a number sign (#) at the start of a line to specify a
comment. You can also use an asterisk (*) as the last character in an entry as a
wild card. The file must be saved in the ASCII file encoding.
Figure 1. Examples of client allowlist files where CICS Explorer is the client
# CICS Explorer User-Agent header
IBM_CICS_Explorer/5.5.6.201912070533 IBM_zOS_Explorer/3.2.9.201912061644 JRE/1.8.0_211 (Windows 7)
If a user attempts to connect to the CMCI JVM server from a client that is not in
the allowlist, the request is rejected with HTTP code 403. If you want to return a custom
response text to the user, continue with step 3.
Optional:
In the JVM profile for the CMCI JVM server,
EYUCMCIJ.jvmprofile, add the following line, where
response_text is your message to the user:
For each valid user-agent that is processed in the allowlist, message DFHSJ1410I
is issued. Only user-agents that are defined in the allowlist are allowed to connect to the
CMCI.
Troubleshooting: If no user-agents are allowed access to the CMCI,
there might be an issue with the client allowlist configuration. For example, the file specified in
the com.ibm.cics.jvmserver.cmci.user.agent.allow.list JVM property cannot be
found, or the file contains invalid values. In such cases, message DFHSJ1408 is
issued to CSMT, and message DFHWU4303 is issued to the user who attempts to connect
to the CMCI.
What to do next
Updating the allowlist
The allowlist values in this file are held in a cache, which by default is refreshed by Liberty
cache file monitoring. Liberty cache file monitoring checks whether the file has changed every 10
seconds by default.
If you need to update the list, you might want to override the default by setting the following Java system property in the JVM profile of the CMCI JVM server: