User Tools

Site Tools


Agent Configuration

This page has been deprecated. Please go here for the latest agent.xml configuration

The Replicator Agent’s primary configuration file is agent.xml. This file contains the definitions required to provide the type of replication desired by the customer.

The configuration can contain multiple sections. The first section is required and is for defining the behavior of the agent itself while the other two optional sections allow you to define the various tasks that will be scheduled by the agent and executed by tasks.

Every replicator configuration file starts with the following directive:

<?xml version=“1.0” encoding=“ISO-8859-1” ?>

The agent.xml file wraps all of its directives within the <config> and then <agent> elements as outlined below.

            <!-- Additional configuration directives goes here -->

Encrypting fields inside the config file

Encrypting sensitive field values is supported in the config.xml and agent.xml files. The installer by default will tag any password field for encrypting by prefixing the value with “encrypted:”. When the agent starts, any configuration values prefixed with “encrypt:” will be encrypted and the configuration file will be rewritten with the prefixes changed to “encrypted:”.


There are two types of tasks, subscribers and sharers. The agent.xml file supports two types of tasks, subscribers and sharers. These task types use the following configuration directives respectfully.

Type Example
Subscriber <subscribe>
Sharer <share>


A Subscriber, also known as a consumer, is configured to monitor a message bus queue for messages that will typically represent a modification to a table. The subscriber handler will use it's task configuration and logic to perform the required replication.


A Sharer, also known as a producer, typically monitors a table for changes and when a change occurs it creates a message representing the change and placed it into a defined queue within the message bus. A subscriber monitoring the configured queue will perform the work associated with the table change.

The current directives which are common to both types of task are outlined in the following table. When stated that the element can be overridden by a task, that directive is global for all task entries but any individual task can alter the value to meet the specific needs of that task.

Directive Example Use Default
task_name <task_name>mysql_replication</task_name> Unique name among tasks Required
handler <handler>Java Class Handler</handler> Java Replicator Class Required

The task name can only contain the following characters; The numbers 0-9 and upper or lower case alphabet characters and the _ underscore.


A handler is the actual software or Java class that's defined using the <handler> directive to perform the replication.

Each handler will have access to its <task> section of the overall configuration. As already stated, there are two types of handlers that can be configured within the <agent> tag, the subscriber <subscribe> and the sharer <share>. Each of these directives will have zero or more nested <task> elements. Each <task> element will likely have unique directives that are required so the handler can perform its work. Each of these directives will be documented along with the handler.

The following tables reflects required configuration directives by task type:

Subscribe Directive Example Use Default
decryption_key <decryption_key>shared secret key</decryption_key> Secret key shared with the instance Required
max_reads_per_connect <max_reads_per_connect>1500</max_reads_per_connect> Messages to consume per interval Optional
Share Directive Example Use Default
encryption_key <encryption_key>shared secret key</encryption_key> Secret key shared with the instance Required
max_writes_per_connect <max_writes_per_connect>1500</max_writes_per_connect> Messages to produce per interval Optional

The following table reflects the available optional configuration directives:

Directive Example Use Default
amqp_uri <amqp_uri>amqp://localhost</amqp_uri> Primary Message Bus Location Optional
amqp_user <amqp_user>admin</amqp_user> User for logging into primary bus Optional
amqp_password <amqp_password>adminadmin</amqp_password> User's password for message bus Optional
report_queue_uri <report_queue_uri>amqp://localhost</report_queue_uri> Message bus for reporting Optional
report_queue_user <report_queue_user>reporter1</report_queue_user> User for reporting Optional
report_queue_password <report_queue_password>reporter1pass</report_queue_password> User password for reporting Optional
polling_interval <polling_interval>20</polling_interval> Interval between each run Optional
schedule <schedule>* * * * *</schedule> Process messages every minutes Optional

Configuring the Transport Protocol

Starting in version 3.2.2, the ability to use the HTTP(S) protocol to communicate with the message bus is available. This transport protocols http and https can be used with the following directives:

amqp_uri and report_queue_uri

The configuration is simple, yet subtle. You simply change the 'schema' used from amqp to http or https as reflected below in the example.

Directive Example Use Default
amqp_uri <amqp_uri></amqp_uri> Primary Message Bus Location Required
amqp_uri <amqp_uri></amqp_uri> Primary Message Bus Location Required

Enabling use of an HTTP Proxy

Also available in relase 3.2.2 and newer is the ability to force HTTP(s) message bus traffic to traverse an HTTP(s) proxy. Several organizations use such a proxy to provide a more secure or controlled method in which to access servers within the Internet.

Once you've configured use of the HTTP or HTTPS protocol as described above you need to add a statement similar to the following to your configuration.


This example will route all http(s) based traffic destined for a Perspectium Message Bus through the proxy Note, that in this example the data is in clear text. In the following example the traffic to the proxy is encrypted via an SSL connection.


Configuring Multiple Agents

Although you can run multiple tasks within a single agent, you can also run multiple agents, each within its own process. A common strategy is to have an agent for production work and another agent for testing/development work. This also has the added benefit of separation of any analytic data we collect and provide to you on the Dashboard.

In order to run multiple agents effectively requires modifying three entries within each agents wrapper.conf file which is within the conf directory.

The entries are:

# Name of the service

# Display name of the service
wrapper.displayname=Perspectium Replicator Agent1

# Description of the service
wrapper.description=Perspectium Replicator Agent1

In the examples above we've ensured uniqueness of the agent by adding an instance number, 1, to the standard name associated with each entry.

A second Agent would have entries such as the following:

# Name of the service

# Display name of the service
wrapper.displayname=Perspectium Replicator Agent2

# Description of the service
wrapper.description=Perspectium Replicator Agent2
replicator_agent.txt · Last modified: 2018/11/05 11:37 by timothy.pike