Configuring Replication
Replication in Bloomreach Content uses a push-based approach. When changes occur in the source repository, the system packages and sends these changes to the target repository. Most replication processing, control, and configuration occurs on the source side. The main configuration node for replication is located at /hippo:configuration/hippo:modules/replication/hippo:moduleconfig.
Configuring the Replication Target
To enable replication, configure the source repository with the correct target URL and credentials for the user account on the target repository.
Starting with brXM 15.1.0, you can configure multiple replication targets.
brXM 14.x and 15.0.x (Single Replication Target)
Under /hippo:configuration/hippo:modules/replication/hippo:moduleconfig/targets, add a node of type hipposys:moduleconfig.
Set the location property to the target's replication REST service URL, for example: http://host[:port]/cms/ws/replication-target.
Set the username and password properties to the credentials of a valid user on the target repository. This user must have the restuser role for the /hippo:configuration/hippo:domains/replication-rest domain. By default, all users in the admin group have this authorization.
brXM 15.1.0 and Later (Single or Multiple Replication Targets)
Under /hippo:configuration/hippo:modules/replication/hippo:moduleconfig/targets, add a node of type replication:target.
Set the replication:location property to the target's replication REST service URL, for example: http://host[:port]/cms/ws/replication-target.
Set the replication:username and replication:password properties to the credentials of a valid user on the target repository. This user must have the restuser role for the /hippo:configuration/hippo:domains/replication-rest domain. By default, all users in the admin group have this authorization.
Example configuration for a replication target:
/hippo:configuration/hippo:modules/replication/hippo:moduleconfig/targets/targetdemo: jcr:primaryType: replication:target replication:location: http://127.0.0.1:9080/cms/ws/replication-target replication:password: admin replication:username: admin
Adjusting Replication Settings
You can modify several properties under /hippo:configuration/hippo:modules/replication/hippo:moduleconfig on the source to control replication behavior:
| Property name | Multi-valued | Default | Needs Restart | Description |
|---|---|---|---|---|
| monitorinterval | no | 10000 | no | Interval (ms) for monitoring the repository journal for changes. |
| packagerinterval | no | 10000 | no | Interval (ms) for processing and sending queued changes to the target. |
| syncbundlesize | no | 100 | no | Number of replication scopes bundled in a single package during sync. |
| synctraversalthrottlems | no | 100 | no | Throttle (ms) per 100 nodes during full-sync traversal. Available from 15.7.10 and 16.9.3. |
| ignoredeventpathpatterns | yes | yes | List of regex patterns for events the change monitor should ignore. | |
| maxbinarysize | no | 10485760 (10MB) | yes | Maximum binary size to replicate. Use -1 for no limit. |
On the target, under /hippo:configuration/hippo:modules/replication-target/hippo:moduleconfig, you can adjust:
| Property name | Multi-valued | Default | Needs Restart | Description |
|---|---|---|---|---|
| importbatchsize | no | 50 | no | Number of scopes saved per session.save() during import. Available from brXM 15.7.10 and 16.9.3. |
You can also configure timeouts for each target by setting properties on the replication:target node under /hippo:configuration/hippo:modules/replication/hippo:moduleconfig/targets/:
| Property name | Type | Default (ms) | Needs Restart | Description |
|---|---|---|---|---|
| pingConnectionTimeout | Long | 5000 | no | Connection timeout for pinging the target. |
| pingReceiveTimeout | Long | 10000 | no | Data receive timeout for pinging the target. |
| replicationConnectionTimeout | Long | 5000 | no | Connection timeout for replication to the target. |
| replicationReceiveTimeout | Long | 120000 | no | Data receive timeout for replication to the target. |
| statusTimeout | Long | 10000 | no | Timeout for status updates. |
Including and Excluding Nodes
For a node to be replicated, it must be located under a path configured for inclusion and must not be under a path configured for exclusion or ignore. Configure these paths on /hippo:configuration/hippo:modules/replication/hippo:moduleconfig/metadata using the multi-valued properties excludedpaths and includedpaths. You do not need to restart the system after changing these properties.
Starting with brXM 15.7.10, you can also configure per-target exclude and ignore paths. These are added to the global settings and allow fine-grained control over which content is replicated to each target. Add these paths on the target's configuration node:
/hippo:configuration/hippo:modules/replication/hippo:moduleconfig/targets/targetdemo: excludedpaths: [/content/documents/folder1, /content/documents/folder2, /content/documents/folder3] ignoredpaths: [/content/gallery] jcr:primaryType: replication:target replication:location: http://127.0.0.1:9080/cms/ws/replication-target replication:password: admin replication:username: admin
Ignoring Nodes
When you exclude a path from replication, nodes under that path are not replicated from source to target. Additionally, any such nodes present on the target are removed. For scenarios where content is created only on the target (such as user comments) and should not be removed by replication, add the relevant path to the ignoredpaths property on /hippo:configuration/hippo:modules/replication/hippo:moduleconfig/metadata on the source. The ignored path must exist on the source for this to take effect.
For example, to prevent removal of user comments stored in /content/documents/comments on the target:
- Create the folder
/content/documents/commentson the source. - Add
/content/documents/commentsto both theexcludedpathsandignoredpathsproperties on/hippo:configuration/hippo:modules/replication/hippo:moduleconfig/metadataon the source.
Authentication
To prevent the target from accepting content from untrusted sources, configure Tomcat to use two-way SSL authentication for the replication REST service. This ensures that only connections with valid and known certificates are accepted on both the source and target.
For Tomcat SSL/TLS setup instructions, refer to the Tomcat SSL/TLS Configuration HOW-TO.
Replication SSL Authentication Example
The following example enforces SSL and client certificate validation on the target. The server name in the certificate must match the actual server name. To log connection issues, configure log4j to log org.apache.cxf at the INFO level.
Replication Target Configuration
Configure the Tomcat connector on the target to require client certificates:
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" maxThreads="150" SSLEnabled="true" scheme="https" secure="true" clientAuth="true" sslProtocol="TLS" truststoreFile="/home/hippo/.keystore" truststorePass="changeit"/>
Replication Source Configuration
Configure the source to provide a certificate using Java system properties. The target will validate this certificate using its trust store. Example configuration using Cargo systemProperties in a test environment:
<javax.net.ssl.keyStore>/home/hippo/.keystore</javax.net.ssl.keyStore> <javax.net.ssl.keyStorePassword>changeit</javax.net.ssl.keyStorePassword>
Database Journal Entry Cleanup
When the Replication module is enabled, it creates an entry in the REPOSITORY_LOCAL_REVISIONS database table. The entry key follows the pattern _HIPPO_EXTERNAL_REPO_SYNC_<module-name>, where <module-name> is taken from the replication module's configuration node at /hippo:configuration/hippo:modules/<module-name>. By default, the key is _HIPPO_EXTERNAL_REPO_SYNC_replication.
This entry tracks the last successful replication revision. It prevents the REPOSITORY_JOURNAL table from being cleaned up past this revision during Repository Maintenance operations, ensuring that unprocessed changes are not lost before replication.
Important: If you remove the Replication module from your project, this entry is not deleted automatically. You must manually remove the entry from the database to avoid orphaned records that could block journal cleanup:
DELETE FROM REPOSITORY_LOCAL_REVISIONS
WHERE JOURNAL_ID = '_HIPPO_EXTERNAL_REPO_SYNC_replication';
Troubleshooting
Replication is Slow or Full Sync Takes Too Long
If replication performance is lower than expected or a full sync takes several hours, default configuration settings may be limiting throughput. The following tuning steps can improve sync times. Apply these changes incrementally in a pre-production environment and measure the impact after each step.
All properties below are set on /hippo:configuration/hippo:modules/replication[-target]/hippo:moduleconfig.
Step 1: Reduce the Source-Side Packaging Interval (packagerinterval)
Lower the packagerinterval from the default 10000 ms (10 seconds) to 5000 ms (5 seconds). If stable, reduce further to 2000 ms (2 seconds). This decreases the delay between packaging cycles, allowing changes to be picked up and sent to the target more quickly.
Step 2: Increase the Source-Side Sync Bundle Size (syncbundlesize)
Increase syncbundlesize from its default to 500, and then to 1000 if stable. This allows more documents to be grouped into a single replication package, reducing the number of packages and improving efficiency.
Step 3: Increase the Target-Side Save Batching (importbatchsize)
Increase importbatchsize to speed up data persistence on the target during full sync. This reduces the overhead of frequent JCR session saves.
Step 4: Decrease the Source-Side Throttling (synctraversalthrottlems)
Reduce synctraversalthrottlems to speed up node traversal during full sync. Note that lowering this value can impact overall CMS performance on the source, and improvements to replication speed may be marginal.
| Property | Default | Recommended (start) | Recommended (next) |
|---|---|---|---|
| packagerinterval | 10000 | 5000 | 2000 |
| syncbundlesize | 100 | 500 | 1000 |
| importbatchsize | 50 | 75 | 100 |
| synctraversalthrottlems | 100 | 100 | 10 |
Warning: Always test configuration changes in a pre-production environment before applying them to production. Monitor replication throughput and system resource usage (CPU, memory, network) after each change.