Cache Agent XML Parameters

The XML elements for both Root and Remote MPX Cache Agents are summarized in the following sections. Unless otherwise stated, all integer parameters have very large positive ranges. For example, all time values have a range of 1 to 2,147,483,647. In most cases, you should consider the default value the minimum setting. Use a practical upper limit based on common sense. For example, if you set the CacheCheckInterval at 10,000,000, the cache will only be checked once every 4 months or so, which makes cache management ineffective.

The following tables describes the XML parameters for Remote and Root MPX Cache Agent.

Parameters Used by Any MPX Cache Agent

The following table describes the parameters used by Remote or Root MPX Cache Agents.

CacheCheckInterval

Integer; number of seconds. The default is 60.

The frequency with which the MPX Cache Agent compares its cache size to the configured cache limit (MaxCacheSize). When the total cache size exceeds the configured limit, least-recently-used files are removed from the cache until the cache size is under the configured limit.

Minimum value is zero, which disables the feature.

CachePath

Path. The default is "/MPXCacheAgent/Cache".

The root folder of the MPX Cache Agent's local cache. Cached files are stored in compressed, encrypted format within subfolders of this path.

As files are requested from the Root MPX Cache Agent either by “downstream” MPX Cache Agents or by clients, they are compressed, encrypted, and stored in a folder tree rooted at the specified directory. The local cache makes secondary file access faster, and it removes I/O contention with files in the server configuration’s vault.

The Root MPX Cache Agent uses the StarTeam Server configuration’s cache.

CacheTypes

Specifies the type of information that will be cached by the MPX Cache Agent. If this group is not specified, the MPX Cache Agent caches file contents only.

Certificate  Location of the digital certificate to be used for TLS protocol, in PEM format.
CertificateKey Location of the digital certificate key file used for TLS protocol.
ObjectTypes

Specifies one or more object types to be cached by the MPX Cache Agent. If this group is specified with the attribute AllTypes="True", then all object types are cached by the MPX Cache Agent. Otherwise, the object types cached are defined by child <ObjectType> elements. If this group is not specified, no object types are cached by the MPX Cache Agent. The object types listed in the Remote MPX Cache Agent must be the same or a subset of the object types listed in the Root MPX Cache Agent.

ObjectType

A valid object type such as Change, File, Folder, Requirement, Task, Topic or the name of a Custom Component created for this installation. The special entry $CustomComponent$ can also be used.

Caching File objects means that artifact properties are cached, which is independent from caching file content.

The $CustomComponent$ setting is used to cache all custom components, including new ones added while the server is running. This can be used instead of adding separate entries for each custom component created, which would require restarting the MPX Cache Agent.

InboundAddresses

Comma-separated list of IP addresses. By default, the MPX Cache Agent uses a list of its machine's IP addresses.

Returned by the MPX Cache Agent in "poll" responses, this list also appears as the "Inbound Addresses" value on the MPX Cache Agent's status page.

In cases where some addresses should be hidden from clients (for example, they are not routable) or the MPX Cache Agent has additional addresses that should be presented to clients (for example, an additional address assigned by a firewall's NAT), this option can be used to control exactly what list is presented to clients.

InitialRequestThreads

Integer; number of connections. The default is 10. The range is from 1 to MaxConnections.

The initial number of request handler threads launched when the MPX Cache Agent starts. Additional request handler threads are launched, up to MaxConnections, as needed when all current threads are dedicated to active connections.

ListenAddresses

Comma-separated list of IP addresses. By default, the MPX Cache Agent binds to the "system" address (IPADDR_ANY), which allows it to receive connections from all available physical (for example, NIC) and logical (for example, VPN) IP addresses.

This list allows you to control the exact set of IP addresses with which the MPX Cache Agent will listen for inbound connections. This list must contain only IP addresses that are valid for the current host and/or the loopback address (127.0.0.1) that allows connections only from the local host.

Unless the InboundAddresses value is specified, the addresses provided in this option are used in poll requests and displayed in the "Inbound Addresses" value on the MPX Cache Agent's status page.

ListenTLS Enables TLS protocol for listening port.
MaxCacheSize

Integer; number of bytes. The default is 1000000000. The range is 0 to approximately 8 exabytes.

The maximum size of the MPX Cache Agent's cache in bytes. If this value is zero, the cache size will not be constrained. Otherwise, files are periodically deleted on a least-recently-used basis to maintain the specified size.

The actual total size of the cache may rise above this value momentarily while new files are received.

MaxCatchupSize

Integer; number of bytes. The default is 100MB. The range is 0 to 263-1.

For a Root MPX Cache Agent, this parameter constrains the maximum number of files returned in a catch-up request. For a Remote MPX Cache Agent, this parameter constraints the maximum number of files requested in a catch-up request. In both cases, the value is the total size in bytes of the files in the catch-up operation. If this value is 0, the catch-up request is unconstrained. In a given catch-up operation, the smaller of the requester's and the requestee's MaxCatchupSize is used to constrain the operation.

MaxConnections

Integer; number of connections. The default is 100. The range is 1 to 1000.

The maximum number of simultaneous connections that the MPX Cache Agent will accept. This value controls the maximum number of request handler threads used by the MPX Cache Agent. If all request handler threads have been started and are in use when a new connection is received, it is queued until a request handler becomes available.

A larger value than the default could be used in highly concurrent environments, at a cost of more memory and potentially more demand on the MPX Cache Agent. A smaller number is generally unnecessary. The maximum is limited by OS/process issues.

MessageBroker

Required group. A group for specifying Message Broker parameters. Minimally, a MPX Cache Agent's MessageBroker group should contain the <Name> tag and a value for the server_names parameter.

The <Name> property in the <MessageBroker> section indicates what type of messaging will be used with this configuration. ActiveMQ MPX Transmitter designates the use of ActiveMQ-type messaging and brokers.

A Remote MPX Cache Agent uses a Message Broker connection to receive file content messages from the content source(s) that it is monitoring. It also uses the Message Broker connection if is a “public” MPX Cache Agent that will respond to poll messages. (See SharePolicy.)

server_names

Defines the publish/subscribe messaging service to be used by the MPX Cache Agent in the format tcp:host:port.

The default is the value “_node” which is equivalent to “localhost”. To use the default, the Message Broker must be on the same computer as the MPX Cache Agent.

host must be the name or IP address of the Message Broker computer, and port must be the port number with which the Message Broker is receiving connections (61616 by default). Example: tcp:MBServer1:61616.

server_start_delay

Integer. Number of seconds. The default is 10.

Specifies the interval between attempts to reconnect to the Message Broker.

socket_connect_timeout

Integer. Number of seconds. The default is 5.

Controls how long in seconds the Event Transmitter, MPX Cache Agent, or StarTeam client waits to connect to the Message Broker before giving up. The default is good for most environments. Minimum value is zero, which disables the feature.

MemoryCacheMaxSize

The maximum amount of memory in bytes that will be used for memory caching. When enabled, most-recently-used cached objects are buffered in memory. A value of 0 disables memory caching. If this value is not specified, the default value is 100MB. This value appears as Memory Cache Max Size (bytes) on the MPX Cache Agent’s status page.

MemoryMaxCacheObjectSize

The maximum size of an object that will be cached in memory. When memory caching is enabled, only new and recently accessed objects at or below this size in bytes will be memory cached. If this value is not specified, the default value is 10KB. This value appears as Memory Cache Max Object Size (bytes) on the MPX Cache Agent’s status page.

RequestPort

Integer; port number. The default is 5201. The range is 1 to 65535.

The port number with which the MPX Cache Agent receives requests. The port number cannot be in use by any other process on the same host.

RequestReadTimeout

Integer; number of seconds. The default is 30.

Specifies the time which a MPX Cache Agent will wait to read the next request from a client before passively closing the corresponding connection. When the connection is closed, the request handler thread is freed-up to service other connections.

Minimum value is zero, which disables the feature.

SharePolicy

Public or Private. The default is Public.

Indicates whether or not this MPX Cache Agent advertises the server GUIDs for which it is caching data. A cache-aware MPX client can broadcast a "poll" request to look for MPX Cache Agents that are caching data for a specific StarTeam Server GUID. Public MPX Cache Agents will respond to such requests when they are caching the requested server's content, but private MPX Cache Agents will not.

Back to top

Parameters Used by Remote MPX Cache Agent

The following table describes the parameters used exclusively by the remote MPX Cache Agent.

CatchupCheckInterval

Integer; number of seconds. The default is 300.

The interval in which a remote MPX Cache Agent will check to see if any of its cache sources require catch-up because the Message Broker connection was lost. When catch-up is required, catch-up cycles continue to be performed until normal Message Broker connectivity has been resumed.

Minimum value is 1.

ContentSource

Each ContentSource group specifies a StarTeam Server configuration that the Remote MPX Cache Agent will monitor for new file content via MPX messages. Optionally, this group specifies an "upstream" MPX Cache Agent that will be contacted for catch-up and forwarding requests. A Remote MPX Cache Agent can have one or more ContentSource groups.

It can contain the following parameters:

ServerGUID

This value must be specified within each ContentSource group. It must be the GUID of the StarTeam Server that this remote MPX Cache Agent will track.

It is used to establish the publish/subscribe “subjects” used to monitor new file content. If the GUID is specified incorrectly, the MPX Cache Agent will not receive new file content.

To locate the GUID for a specific server configuration:

  1. From the Server Administration, select the server.
  2. Click the Properties icon on the toolbar or click Server > Server Properties. These actions display the Properties dialog box.
  3. Copy the GUID from the server configuration’s Properties dialog box and paste it into the .xml file.
Projects

If specified, this group value indicates that not all content for the corresponding StarTeam Server is to be tracked. Instead, only content for each Project parameter within the Projects group will be tracked and stored. It contains one or more Project parameters.

Project

Each Project parameter specifies one project name or name pattern. All files checked into a project whose name matches the specified name or pattern are cached by the MPX Cache Agent. A pattern is a name that contains one or more asterisk (*) wildcard characters.

For caching purposes, each file revision "belongs" to the project it is checked in to. In practice, a file could be shared among multiple projects and a given check-in may cause the corresponding file revision to appear in multiple projects. Because the file content is "broadcast" with the project name it was checked into, only Remote MPX Cache Agents tracking that project will store the file. For example, suppose a file is shared between projects P1 and P2, and a new revision of the file is checked into project P1. Only Remote MPX Cache Agents tracking project P1 store the new file revision. A Remote MPX Cache Agent tracking only project P2 will not receive the broadcast. However, "pull through" caching, explained more below, allows the Remote MPX Cache Agent that is tracking only project P2 to obtain the file revision anyway.

When a Remote MPX Cache Agent is configured to track specific projects, it still accepts requests for any file. If a requested file is not in its local cache, a Remote MPX Cache Agent forwards the request to the appropriate Root MPX Cache Agent and stores it locally for future requests, regardless of which projects the file belongs to. In other words, tracking-by-project limits files visible to Remote MPX Cache Agents by "push" caching, but it does not limit the files a Remote MPX Cache Agent can store via "pull through" (request forwarding) caching.

UpstreamCache

This group specifies that an upstream MPX Cache Agent will be contacted for catch-up and forwarding requests for content related to the corresponding StarTeam Server. The upstream MPX Cache Agent can be automatically located or explicitly configured as specified by the group’s parameters: AutoLocate, UpstreamHost, UpstreamPort, UpstreamTLS, and UpstreamCertificate.

If a ContentSource parameter does not contain an UpstreamCache parameter, catch-up and miss forwarding will not occur for the corresponding server configuration.

When used, UpstreamCache must contain either an UpstreamHost or an AutoLocate parameter. The two are mutually exclusive.

UpstreamHost (along with UpstreamPort) explicitly specifies the upstream MPX Cache Agent, while AutoLocate requests polling.

UpstreamTLS enables TLS connections to Upstream Cache Agent.

UpstreamCertificate specifies the location of the SSL certificate of the RootCAche Agent, in PEM format

AutoLocate

Indicates that the Root MPX Cache Agent for the corresponding StarTeam Server configuration is to be automatically located and used as the upstream MPX Cache Agent. Remote MPX Cache Agent to continue periodic polls for a Root MPX Cache Agent until one is found. It is an empty tag and mutually exclusive with UpstreamHost.

UpstreamHost

Explicitly identifies the host name or IP address of the upstream MPX Cache Agent to be used for content related to the corresponding StarTeam Server. This parameter is mutually exclusive with AutoLocate.

UpstreamPort

Integer. The default is 5201. The range is from 1 to 65535.

Only meaningful if UpstreamHost is specified, this parameter specifies the port number of the upstream MPX Cache Agent.

PrechargeSize

Integer. The default is MaxCatchupSize.

Specifies the maximum size of a Remote MPX Cache Agent's first catch-up operation, which is used to precharge its cache. It defaults to the MPX Cache Agent's MaxCatchupSize, but it can be specified larger or smaller than that value. If this value is zero, the Remote MPX Cache Agent does not perform an initial pre-charge operation.

Back to top

Parameters Used by Root MPX Cache Agent

The following table describes the parameters used exclusively by the root MPX Cache Agent.

RootCacheAgent

Group for Root MPX Cache Agent parameters as defined below.

ServerConfigsFile This option specifies the full path name of the StarTeam Server configuration file. It is required for object caching.
ConfigName This option specifies the name of the StarTeam configuration that the root MPX Cache Agent will cache. It must be used in conjunction with the <ServerConfigsFile> option.
PreCharge

Specifies whether the root MPX Cache Agent should "pre-charge" its local cache with missing object revisions by scanning the database at start-up time. Values include:

"None" A pre-charge is not performed.
"TipsOnly" (Default). Only tip revisions are added to the local cache.
"All" All object revisions are added to the local cache. This option is ignored if the <ObjectTypes> option is not specified.
RootRepositoryPath Required. The full path name of the StarTeam Server configuration's repository folder. This option is needed only when ServerConfigsFile is not used.
RootHiveIndexPath The full path of the StarTeam Server's Native-II hive index file. The default is RootRepositoryPath/HiveIndex/hive-index.xml.
RootJournalPath The full path name of the StarTeam Server configuration's cache journal file, which is created by the File Transmitter. The default is RootRepositoryPath/CacheJournal.dat.

Back to top