MPX Cache Agent installation

This topic describes the MPX Cache Agent installation.

About the MPX Cache Agent

You need to install a MPX Cache Agent only once on any computer that will use one or more MPX Cache Agents. You run as many instances of MPX Cache Agents as you need, each with a different and appropriate XML file.

The default XML file for a root MPX Cache Agent is RootCAConfig.xml. The default XML file for a remote MPX Cache Agent is RemoteCAConfig.xml. As you install a MPX Cache Agent, you also set up an initial MPX Cache Agent configuration file, so you must select either a Root or Remote MPX Cache Agent during the installation. This does not stop you from creating another configuration file for the same or a different type of MPX Cache Agent later on that same computer.

Back to top

Upgrading the MPX Cache Agent - Windows

The MPX Cache Agent can be installed on a machine with a previous release.

Note: The goal is to transition StarTeam Server configurations from the older to the newer release.

The MPX Cache Agent can be run as either an application or a service. You can run multiple MPX Cache Agent instances on the same machine, but each needs its own configuration file.

By default, the installation creates a manual MPX Cache Agent service for your convenience. If the installation detects that a MPX Cache Agent service (for example, HKEY_LOCAL_MACHINES\SYSTEM\ControlSet001\Services\CacheAgentService) already exists and is registered, the installation does not set up a service. A warning advises

  • If the existing MPX Cache Agent service is no longer needed, uninstall the previous MPX Cache Agent release or use the previous release to run CacheAgentService -unregister from a console window to unregister the existing MPX Cache Agent. Note that this is optional and the older release can remain, including the services created for it.
  • Create an appropriate configuration file for each MPX Cache Agent service desired for the release just installed. You can reuse configuration files from the previous release of MPX Cache Agent by copying them to the new location. You might need to rename them for use with multiple MPX Cache Agent instances.
  • Using the release just installed, run CacheAgentService -register from a console window for each MPX Cache Agent service desired. Note that the "-name" parameter is used to define a unique service name for each new service created.
  • If an older MPX Cache Agent is installed, you are not asked whether you are installing a root or remote MPX Cache Agent and are not asked for any configuration information. The sample files (SampleRemoteCacheAgentConfig.xml and SampleRootCacheAgentConfig.xml) are installed (as always), but neither the RootCAConfig.xml nor the RemoteCAConfig.xml file is created.

See the appropriate MPX Administrator’s Guide available on the StarTeam > StarTeam Server <version> > Documentation menu for more information about configuring MPX Cache Agents.

Back to top

Before Installing an MPX Cache Agent - Windows

When installing an MPX Cache Agent that will be used as a root MPX Cache Agent, StarTeam Server must be installed first. After you have installed StarTeam Server, you can install the other components in any order.

The following is a recommendation for installing MPX components:

  1. Install StarTeam Server. The MPX Event Transmitter and MPX File Transmitter are installed automatically with StarTeam Server.
  2. Install ActiveMQ MPX Message Broker.
  3. Install the root MPX Cache Agent. You need to install it only once per machine, even when that machine has more than one server configuration. You run multiple instances to support multiple StarTeam Server configurations. Each server configuration must have its own root cache agent instance.
  4. Install the remote MPX Cache Agent. This is the same installer as the root MPX Cache Agent. The remote MPX Cache Agents can use the same Message Broker as the root MPX Cache Agent, but multiple Message Brokers are suggested for distributed teams, especially over distances. In practice, remote MPX Cache Agent usually use remote Message Brokers.

    Before you start a root MPX Cache Agent:

    1. Start each server configuration that you will use with MPX Cache Agent. Doing this causes the MPX File Transmitter to generate or upgrade a CacheJournal.dat file for each configuration.
    2. (Optional) Modify the MaxJournalAge parameter’s value in the FileTransmitter.xml file to represent the maximum number of days for which records will be kept within the Journal file. The pre-configured value is 180 days. Note that the Journal file is “trimmed” of expired records (those whose age exceeds the MaxJournalAge value) only when the server configuration is started.

Back to top

Installing an MPX Cache Agent - Windows

Whether a MPX Cache Agent operates as a root MPX Cache Agent or a remote MPX Cache Agent is determined solely by its configuration. The installation of the MPX Cache Agent is similar in both cases except for consideration of the computer on which to install it:

  • The root MPX Cache Agent requires access to the vault for the server configuration that it services. Consequently, it is usually installed on the same computer as the Server. Alternatively, if it can be installed on a network-near computer to prevent the Root MPX Cache Agent from competing for CPU or network I/O with the corresponding server configuration. However, this requires it to access the vault files and the CacheJournal.dat file by way of a shared network drive, so use this option only when a high-speed network is in place .
  • Remote MPX Cache Agents should be installed in each geographic location that can benefit from local data access. One approach is to install a MPX Cache Agent in each network environment that local users can access over a highspeed LAN. (For example: Install two remote MPX Cache Agents at headquarters, one each for engineering and QA; install one at each regional office.) Another beneficial use of the MPX Cache Agent is to install an instance on a computer dedicated to a check-out intensive application such as a build utility. There is no limit on the number of MPX Cache Agents that can be installed throughout an enterprise. However, keep in mind that each MPX Cache Agent requires access to a Message Broker. For more information about clouds, see “Understanding Clouds” in the appropriate MPX Administrator’s Guide.

To install a root MPX Cache Agent or remote MPX Cache Agent on Microsoft Windows:

  1. Log on to the computer as the administrator or as a user with administrative privileges.
  2. Navigate to the directory that contains the downloaded files.
  3. Run the downloaded installer.
  4. Select a language from the list, and then click OK.
  5. On the License Agreement page, read the agreement. If you agree with the license agreement, click I accept.... If you do not accept the license agreement, you cannot install the product.
  6. On the Choose Install Folder page, browse for the location to be used as the installation folder.

    The default installation path is C:\Program Files\Micro Focus\MPX Cache Agent <version>.

  7. Choose a Root MPX Cache Agent or Remote MPX Cache Agent installation.

    Root MPX Cache Agent installation

     

    Message Broker Address

    Enter the host name or address of the Message Broker that the Root MPX Cache Agent will use to communicate with other MPX Cache Agents and clients. This value can optionally include the protocol prefix (tcp:) and port number suffix (:1234). The port number must be provided if the Message Broker is not using the default port (61616 for ActiveMQ MPX). For example: tcp:MBServer1:5123

    Server Cache folder

    Click Choose to browse to the folder path that contains the vault cache of the server configuration that the MPX Cache Agent will serve. This path must be relative to the computer on which the Root MPX Cache Agent is being installed.

    Remote Cache Agent installation

     

    Message Broker Address

    Enter the host name or IP address of the Message Broker that the Remote MPX Cache Agent will use to receive file content messages and to communicate with other MPX Cache Agents and clients. A Remote MPX Cache Agent should be configured to use a Message Broker and the tcp: address.

    This option is described in more detail in “Configuring a Remote Cache Agent” in the in the MPX Administrator’s Guide.
  8. On the Choose Shortcut Folder page, use the default setting (that is, keep the Other option button set to C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Micro Focus\MPX Cache Agent <version>).
  9. On the Pre-installation Summary page, review the settings and click Previous one or more times if you want to change the installation options. Then return to the Pre-installation Summary page, and click Next or Install.
  10. On the Install Complete page, click Done.

Back to top

After Installing an MPX Cache Agent - Windows

Depending upon your environment, you may have to perform additional steps to use the MPX Cache Agent:

All MPX Cache Agents
  • The MPX Cache Agent installer installs both CacheAgentService.exe and CacheAgentApp.exe so you can run MPX Cache Agent as either a service or a console application.
  • CacheAgentService is configured as a Manual start service. You may want to change the start type to Auto so that the MPX Cache Agent will start automatically thereafter. To change the start type to Auto, use the Control Panel Services interface or unregister and re-register the service. See “Running Cache Agent on Windows” in the appropriate MPX Administrator’s Guide for more information.
Root MPX Cache Agent

The default configuration file for a Root MPX Cache Agent is RootCAConfig.xml. It may need to some modification. See “Configuring a Root Cache Agent” in the appropriate MPX Administrator’s Guide.

Remote Cache Agent

The default configuration file for a Remote MPX Cache Agent is RemoteCAConfig.xml. It needs some modification for your environment. See "Configuring a Remote Cache Agent" in the appropriate MPX Administrator’s Guide.

Back to top

Installing MPX Cache Agent on Linux

This section describes how to install MPX Cache Agent on a Linux machine.

  1. Close all applications.
  2. Navigate to the directory that contains the downloaded files.
  3. Run the downloaded installer.
  4. Run the binary file using the command ./ca.bin. When installing or uninstalling on a non-Microsoft Windows platform, specify the installed Java VM to use as a parameter when running the installer. This step is necessary because Java VMs for non-Microsoft Windows operating systems are not bundled with the installers. If you experience any difficulties when running the command ./ca.bin, add the parameter LAX_VM and specify the path to your VM. For example: ./ca.bin LAX_VM /usr/java/latest/jre/bin/java.
  5. On the Introduction page, read the information, and click Next.
  6. On the License Agreement page, read the agreement. If you agree with the license agreement, click I accept.... If you do not accept the license agreement, you cannot install the product.
  7. On the Choose Install Folder page, browse for the location to be used as the installation folder.
    The default location is /home/starteam/cacheagent14.0.
  8. Click Next.

  9. On the Choose Cache Agent Type page, select the MPX Cache Agent type you wish to install and click Next:

    Root MPX Cache Agent

    Each StarTeam configuration can have one Root MPX Cache Agent. You can install it on the same machine as StarTeam Server or on a separate machine that has access to the configuration's vault cache folder.

    Use the Get Root Cache Agent Settings dialog box to perform the following:

    1. Specify the address of the Message Broker to be used.
    2. Browse to or type the path to the repository of the StarTeam Server configuration.
    3. Click Next.
    Remote MPX Cache Agent

    You can install any number of Remote MPX Cache Agent throughout your organization. Typically, one Remote MPX Cache Agent must be installed in each geographic region. Each Remote MPX Cache Agent is usually chained or tiered to one or more Root MPX Cache Agent.

    Use the Get Remote Cache Agent Settings dialog box to perform the following:

    1. Specify the address of the Message Broker to be used.
    2. Specify the StarTeam Server configuration GUID.
    3. Click Next.
  10. On the Choose Link Folder page, specify whether to create links in your home folder, to create them in another location, or to not create them at all.
  11. Click Next.
  12. On the Pre-installation Summary page, review the settings and click Previous one or more times if you want to change the installation options. Then return to the Pre-installation Summary page, and click Next or Install.
  13. On the Install Complete page, click Done.
    In order to start the MPX Cache Agent, set the environment variable LD_LIBRARY_PATH to point to the lib folder of the Oracle home directory.

Back to top