Running MPX Cache Agents

To run the MPX Cache Agents successfully, start the applications you have installed in the following order:

  1. Message Brokers
  2. StarTeam Server (the server configuration starts the transmitters)
  3. Root MPX Cache Agent
  4. Remote MPX Cache Agent

For more details about starting MPX components see Dependencies - Startup Order for MPX Components.

Running MPX Cache Agent On Microsoft Windows

MPX Cache Agents can be run as service or console applications. Up to 25 Root and Remote MPX Cache Agents can run as services on the same computer. However, only the first one installed on a computer will be registered as a service. It is registered as manual service with the display name MPX Cache Agent and an internal name of CacheAgentService. You will need to register the others.

MPX Cache Agent is stopped automatically when the computer is shut down.

Running MPX Cache Agent as a Service

If a MPX Cache Agent is running as a service, you can start and stop it manually using the Control Panel Services utility. Click Start > Settings > Control Panel > Administrative Tools > Services to see the list of services.

Using the same utility, you can change the MPX Cache Agent service to run automatically when you start Microsoft Windows.

You can also control the MPX Cache Agent service from the command line by running the CacheAgentService.exe. Use any of the following syntaxes:

CacheAgentService -start [ configFile ] [ -log logFile ] [ -verbose ]
CacheAgentService -register [ Manual | Auto] [ configFile ] [ -dependson list ] [ -log logFile ] [ -name serviceName ] [ -verbose ]
CacheAgentService -unregister
configFile

The default configuration file is CacheAgentConfig.xml. If you use multiple configuration files, each one must specify unique values for CachePath and RequestPort so that MPX Cache Agent services do not interfere with each other’s operation.

-dependson list

Specifies service dependencies for the new MPX Cache Agent service. The list must be a quoted, space-separated list of internal (not display) names of the services on which the MPX Cache Agent service will depend. (A service’s internal name is its registry key within the Microsoft Windows registry.)

The most common dependency for a MPX Cache Agent is to make it dependent on the Message Broker service running on the same machine. The Message Broker service’s display name is typically ActiveMQ Message Broker for CM Hub, but its internal name is typically ActiveMQMessageBroker.

Consequently, to make a MPX Cache Agent depend on the Message Broker service on the same computer you would use:

-dependson ActiveMQMessageBroker
-log logFile Specifies a log file name other than the default, which is CacheAgentService.log.
-name serviceName Specifies the display name for the service in the Control Panel’s Services utility. The default is MPX Cache Agent.
-register Register the service with the specified start mode (Manual or Auto), optionally with a specific configuration file at startup.
-start Starts the service, optionally with a specific configuration file.
-unregister Removes a service. For example, if you change the MPX Cache Agent from Manual to Auto, you would unregister it and re-register it. A service must be stopped before it can be unregistered.
-verbose

Causes another more detailed log to be generated. It defaults to CacheAgentService-debug.log.

Examples

Below is an example command-line to register an auto-start MPX Cache Agent service with the name “Prod1 Root CA”, dependent on the ActiveMQ MPX Message Broker, with the default log file name, and verbose logging enabled:

CacheAgentService -register Auto c:\CAConfigs\Prod1RootCA.xml -dependson "ActiveMQMessageBroker" –name "Prod1 Root CA" –verbose

As with the register command, the default service name is “MPX Cache Agent”. That means that the name parameter must be used when you unregister a service that has a non-default name. For example, to un-register the service used in the last example:

CacheAgentService –unregister –name "Prod1 Root CA"

Log File

When MPX Cache Agent runs, it creates a log file in its installation folder. The default file name for the log is CacheAgentService.locale.log where locale is something like en-US.

If a file with that name already exists, it is renamed to include a time stamp: CacheAgentService_YYYYMMDDhhmmss.location.log

Its log can be viewed from a browser by entering a URL using the following syntax:

http://host:port/log
host Identifies the computer on which the MPX Cache Agent is running.
port Provides its configured port number. The default port is 5202.

Back to top

Running MPX Cache Agent As a Console Application

CacheAgentApp.exe can be used instead of the service application. Use it when multiple MPX Cache Agents operate on the same machine against different StarTeam Server configurations.

For this scenario, each MPX Cache Agent uses a different request port and different local cache paths.

When running the CacheAgentApp.exe, you can use the following syntax:

CacheAgentApp [ -c configFile ] [ -l logFile ] [ -v off | on ]
Parameter Description
-c configFile

Starts the MPX Cache Agent as a console application, optionally with a specific configuration file. The default configuration file is RootCAConfig.xml or RemoteCAConfig.xml, depending on the type of the MPX Cache Agent.

-l logFile

Specifies a log file name other than the default, which is CacheAgentApp.log.

-v

Add more detail to the log. The settings are off or on. Off is the default.

Log File

When MPX Cache Agent runs, it creates a log file in its installation folder. The default file name for the log is CacheAgentService.locale.log where locale is something like en-US.

If a file with that name already exists, it is renamed to include a time stamp: CacheAgentService_YYYYMMDDhhmmss.location.log

Its log can be viewed from a browser by entering a URL using the following syntax:

http://host:port/log
host Identifies the computer on which the MPX Cache Agent is running.
port Provides its configured port number. The default port is 5202.

Back to top

Running MPX Cache Agent on Linux

To run a MPX Cache Agent on a Linux system, use the following start command:

cacheagentapp -c RootCacheAgentConfig.xml -d start

To stop a MPX Cache Agent on a Linux system, use the following stop command:

cacheagentapp -c RootCacheAgentConfig.xml -d stop