Configuring the global cache for multiple integration nodes

Configure one or more integration nodes to share data in the global cache by using a cache policy file. Use a cache policy to enhance the availability of the cache by configuring an integration node to host two catalog servers. Also use a cache policy file to host container servers in a multi-instance integration node for high availability.

Before you begin

For more information about the default global cache topology, see Data caching overview.

About this task

Specify a cache policy file for your integration nodes to use by setting the cache policy to the name and file path of the XML cache policy file. Sample policy files are provided in the installation directory install_dir/server/sample/globalcache, covering the following configurations:
  • A single integration node that hosts two catalog servers; if one catalog server fails, the global cache switches to the other one.
  • Two integration nodes that share a catalog server that is hosted by the first integration node.
  • Two integration nodes that each host a catalog server; if one catalog server fails, the global cache switches to the catalog server in the other integration node.
  • Three integration nodes in a high availability scenario. Two integration nodes each host a catalog server, and a multi-instance integration node hosts two container servers. If the active instance of the multi-instance integration node fails, the global cache switches to the container servers in the standby instance.

    For specific instructions to configure the global cache for multi-instance integration nodes, see Configuring the global cache for multi-instance integration nodes.

Two of the sample policies configure the cache to contain two catalog servers. This configuration means that if one of the catalog servers is stopped, the other catalog server is used, and no cache data is lost. However, having more than one catalog server can affect startup time after the integration node is started, until the cache is available. If you have more than one catalog server, you must start at least two of them for the cache to be available. When you configure a cache across multiple integration nodes with multiple catalog servers, if you need to start one integration node before the others then you can configure this integration node to host two catalog servers.

When you set the integration node-level property to a policy file, the policy file is validated against an XML schema. A copy of the XML schema file is provided at install_dir/server/cachesupport/schema.

Do not edit the sample policy files in their original location; copy them to your own file system first. The original sample policy files might be replaced when you apply maintenance to IBM Integration Bus.

You cannot use the policy file to fix specific cache roles to specific integration servers. Instead, you must use the none policy; see Embedded global cache.

The following steps describe how to configure the global cache for multiple integration node.

Procedure

  1. Copy one of the sample policy files from install_dir/server/sample/globalcache to another location on your file system.

    You can place a copy of the same policy file on each computer where an integration node is running, or you can provide a single copy of the policy file in a shared file system for all integration nodes to access.

  2. Modify the policy file for your system, specifying the appropriate an integration node names and listener hosts, the port range that the integration node is to use, and how many catalog servers the integration node hosts. Optionally, you can also specify a domain name for all catalog servers in the embedded cache. If you do not set a domain name, the integration node creates one.
    Ensure that the policy meets the following criteria:
    • You can define 0, 1, or 2 catalog servers for an individual integration node, but at least one catalog server must be defined in the policy.
    • If two integration nodes share a host name, you must set a distinct port range for each integration node.
    • Ensure that the port range for each integration node includes at least 20 ports.
    • The integration node names and listener hosts specified in the policy must match the values defined for the integration node.
    • You can define only one domain name in the policy file.
    • If specified, the domain name must precede the integration node elements in the policy file.
    • The policy file must be encoded in UTF-8.
    • The policy file must contain valid XML. The policy file is validated against an XML schema when you set the integration node-level property. You can also validate the policy file against the copy of the schema (policy.xsd) that is provided in install_dir/server/cachesupport/schema.
    • If you are configuring a multi-instance integration node, an optional listenerHost element is provided as a child of the integration node element so that you can specify more than one listener host. In this situation, the listenerHost attribute of the integration node element is also optional. However, you must specify either the listenerHost element or the listenerHost attribute.
    • If you are configuring a multi-instance integration node, you cannot specify the listenerHost element more than once for an integration node that is configured to host one or more catalog servers.
    • If the policy includes more than one integration node with the same name, and those integration nodes are running on different listener hosts, then you must configure the listenerHost parameter for the cachemanager component on each integration node that is covered by the policy, see Parameter values for the cachemanager component. If you do not configure the listenerHost parameter on each integration node, you get a BIP7137 error message when you apply the cache policy.
    When you use an XML policy file, the integration node-level portRange property is ignored. The port range specified in the XML file overrides the property specified for the integration node.
  3. Save the policy file.
  4. Set the cache policy to the fully qualified name of the policy file.

    The path that you specify must be absolute, not relative. If you use a shared drive on Windows, you must use the \\hostname\directory path syntax to the shared drive, instead of a mapped drive letter. The IBM Integration Bus user ID that is used to access the \\hostname\directory path must have read access to the file system and must use the same password.

    You can set the cache policy by using commands.

  5. Restart each integration node. If your cache is configured for more than one catalog server, then ensure that at least two catalog servers are started.

Results

When each integration node restarts, it uses the values in the policy file to determine its cache properties. Each integration node contains up to 4 container servers. To find out where container servers are placed, use the mqsicacheadmin command to run the showPlacement command, as shown in the following example:
mqsicacheadmin integrationNodeName -c showPlacement
You can also use the mqsicacheadmin command to show cache components in a multi-integration node cache. For example, the listHosts command shows the host names, number of hosts, and number of catalogs in the cache:
mqsicacheadmin integrationNodeName -c listHosts