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.
<config> <agent> <!-- Additional configuration directives goes here --> </agent> </config>
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.
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.
|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:
|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|
|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:
|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|
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.
|amqp_uri||<amqp_uri>http://MessageBrokerService4.perspectium.com:8567</amqp_uri>||Primary Message Bus Location||Required|
|amqp_uri||<amqp_uri>https://MessageBrokerService4.perspectium.com</amqp_uri>||Primary Message Bus Location||Required|
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 192.168.40.131. 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.
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 wrapper.name=agent1 # 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 wrapper.name=agent2 # Display name of the service wrapper.displayname=Perspectium Replicator Agent2 # Description of the service wrapper.description=Perspectium Replicator Agent2