OCEE documentation
OCEE documentation

This page describes how to set up and configure the OCEE Replicator feature.

To configure the OpenCms Replication you will need one master OpenCms instance and one or more OpenCms instances installed on separated machines, making a distinction during the setup process of the master instance and the others.

Please note that the OCEE Replicator needs an installed and working OCEE Cluster manager.  How to configure the cluster can be read in the respective documentation. You will need to configure  your replication master instance as the cluster workplace server, including all replicated instances in the cluster.

Install the first machine as it were a standalone installation, including the OCEE Replicator, or you could also import the module in a previously installed OpenCms instance. Then edit the configuration files, located under the ${OPENCMS_HOME}/WEB-INF/config/ folder,  as follows:

Add the cluster configuration class to the opencms.xml configuration file, adding it under the <configuration> node, as follows:

<configuration>
...
    <config class="org.opencms.ocee.replication.CmsReplicationConfiguration"/>
</configuration>

Activate replication support by modifying the runtime info class, under the <runtimeclasses> node, as follows:

<opencms>
<system>
    ...
    <runtimeclasses>
        <runtimeinfo class="org.opencms.ocee.replication.CmsReplicationDbContextFactory"/>
    </runtimeclasses>
    ...
</system>
</opencms>

Add the new driver sequence in the opencms.properties configuration file, adding it
under the “Configuration of the driver manager” section, as follows:

#
# Configuration of the driver manager
###########################################################################
driver.vfs=\
db
driver.project=\
replication,\
db
driver.user=\
replication,\
db
driver.history=db

Note: If you are using additional drivers, please take care that the first one in every sequence is the cache driver, and the last driver the db driver.

Add the driver classes under the “Configuration of the replication drivers” section (it could be that this section does not exist in your current configuration file), as follows:

#
# Configuration of the replication drivers
###########################################################################
replication.project.driver=org.opencms.ocee.replication.CmsReplicationProjectDriver
replication.user.driver=org.opencms.ocee.replication.CmsReplicationUserDriver

Add a database pool for each replication instance in the opencms.properties configuration file. For this you have to create a new pool and give it a unique new name, let’s say ${REPLICATION_POOL_NAME} , and add it to the “Declaration of database pools” section, as follows:

# Declaration of database pools
###########################################################################
db.pools=\
default,\
${REPLICATION_POOL_NAME}

Then add a database pool configuration section for each replication instance under the “Configuration of the replication pools” section (it could be that this section does not exist in your current configuration file), as follows:

#
# Configuration of the replication pools
###########################################################################
db.pool.${REPLICATION_POOL_NAME}.jdbcDriver=oracle.jdbc.driver.OracleDriver
db.pool.${REPLICATION_POOL_NAME}.jdbcUrl=jdbc:oracle:thin:@localhost:1521:oracle
db.pool.${REPLICATION_POOL_NAME}.jdbcUrl.params=
db.pool.${REPLICATION_POOL_NAME}.user=opencms2
db.pool.${REPLICATION_POOL_NAME}.password=opencms2
db.pool.${REPLICATION_POOL_NAME}.poolUrl=opencms:${REPLICATION_POOL_NAME}
db.pool.${REPLICATION_POOL_NAME}.maxActive=25
db.pool.${REPLICATION_POOL_NAME}.maxWait=2000
db.pool.${REPLICATION_POOL_NAME}.maxIdle=10
db.pool.${REPLICATION_POOL_NAME}.testQuery=
db.pool.${REPLICATION_POOL_NAME}.whenExhaustedAction=block
db.pool.${REPLICATION_POOL_NAME}.testOnBorrow=false

Configure the replication support for each data access driver except for the subscription driver by editing the opencms.properties configuration file under the “Configuration of the database driver manager” section, setting the SQL Manager classes to the right one for your database provider, in this example Oracle 9i/10g:

#
# Configuration of the database driver manager
###########################################################################
...
db.vfs.sqlmanager=org.opencms.ocee.replication.db.oracle.CmsSqlManager
...
db.project.sqlmanager=org.opencms.ocee.replication.db.oracle.CmsSqlManager
...
db.user.sqlmanager=org.opencms.ocee.replication.db.oracle.CmsSqlManager
...
db.history.sqlmanager=org.opencms.ocee.replication.db.oracle.CmsSqlManager

Configure the actual replications in ocee-replication.xml. See the following section for the available configuration options in that file.

Because all of the replication is done by the master server, the replication does not need to be configured on the other servers. The exception to this is if you want to use user backwards replication. in this case, make the following modifications:

Add the new driver sequence under the “Configuration of the driver manager” section, as
follows:

#
# Configuration of the driver manager
###########################################################################
driver.vfs=\
db
driver.project=\
db
driver.user=\
replication,\
db
driver.history=db

Important: The replication driver must only be added for the user driver chain (driver.user).

Note: If you are using additional drivers, please take care that the first one in every sequence is the cache driver, and the last driver the db driver.

Add the driver classes under the “Configuration of the replication drivers” section (it could be that this section does not exists in your current configuration file), as follows:

#
# Configuration of the replication drivers
###########################################################################
replication.user.driver=org.opencms.ocee.replication.CmsReplicationChangedUserDriver

Important: The replication driver here is a different one as configured on the master
server.

Note that you will have to perform an initial full replication of the root folder ("/") to the slave servers

The OCEE Replication module configuration is maintained in the ${OPENCMS_HOME}/WEB-INF/config/ocee-replication.xml XML file. This section describes the configuration options for this file. Be aware that the replication configuration has to be the same on all OpenCms instances in the cluster.

  • Element: /opencms/replication/managersgroup
    Description: This node defines the name of the group that should have the permissions to access the administration tools for the replication.
    Default Value: If it is not set, the default Administrators group will be used.
  • Element: /opencms/replication/handlers
    Description: A list of all configured replication handlers.
    See next section.
  • Element: /opencms/replication/servers
    Description: A list of all configured replication servers.
    See section Replication Servers Configuration.
  • Element: /opencms/replication/server-groups
    Description: A list of configured server groups
    See section Server groups configuration.
  • Element: /opencms/replication/replicationsources
    Description: A list of all configured replication sets of resources.
    See section Replication Sets Configuration.
  • Element: /opencms/replication/exportfolder
    Description: This node is optional and its value should be an accessible RFS folder where the replication history will be exported to, like c:/opencms/replication/ for Windows or /var/opencms/replication for Unix.
    Default Value: Leave it blank or remove the node to disable this feature.
  • Element: /opencms/replication/replicationorder
    Description: A list of folder names defining the replication order.
  • Element: /opencms/replication/replicationorder/resource
    Description: A resource name.
  • Element: /opencms/replication/userreplications
    Description: A list of all configured user replications.
    See section Replication user synchronization configuration.

A replication handler determines how to replicate the resources.
Every replication handler has to be configured in the configuration file, under a separated /opencms/replication/handlers/handler node, which has the following structure:

  • Element: /opencms/replication/handlers/handler/class
    Description: A fully qualified class name that identifies the handler implementation.
  • Element: /opencms/replication/handlers/handler/stats
    Description: Statistical information that will be automatically generated.

The following handler classes are available:

  • To replicate account information: org.opencms.ocee.replication.CmsReplicationAccountsHandler
  • To replicate the resources: org.opencms.ocee.replication.CmsReplicationVfsHandler

A replication server determines where to replicate the resources.
Every replication server has to be configured in the configuration file, under a separated
/opencms/replication/servers/server node, which has the following structure:

  • Element: /opencms/replication/servers/server
    Description: Replication server node.
    • Attribute: /opencms/replication/servers/server@mode
      Description: a mode type, auto or manual. auto mode means that every time a resource is published, it will be replicated. manual mode means that the replication needs to be triggered.
      Default Value: auto.
  • Element: /opencms/replication/servers/server/name
    Description: A nice name for displaying purposes.
  • Element: /opencms/replication/servers/server/description
    Description: A description for displaying purposes.
  • Element: /opencms/replication/servers/server/serverid
    Description: This is an UUID for writing replication history into the publish history.
    Default Value: If it is not set, it will be automatically generated.
  • Element: /opencms/replication/servers/server/origin
    Description: Configures the origin (source) of this replication
  • Element: /opencms/replication/servers/server/origin/server-name
    Description: The name of the origin (source) server of this replication. Should be the same than specified in the ocee-cluster.xml and opencms.properties configuration files.
  • Element: /opencms/replication/servers/server/origin/poolurl
    Description: The database pool URL, something like: opencms:replication, this should be same as configured ${REPLICATION_NAME} of section Master OpenCms Instance Installation.
  • Element: /opencms/replication/servers/server/destination
    Description: Configures the destination of this replication
  • Element: /opencms/replication/servers/server/destination/server-name
    Description: The name of the destination server of this replication. Should be the same as specified in the ocee-cluster.xml and opencms.properties configuration files.
  • Element: /opencms/replication/servers/server/ destination/poolurl
    Description: The database pool URL, something like: opencms:replication, this should be same as configured ${REPLICATION_NAME} of section Master OpenCms Instance Installation.
  • Element: /opencms/replication/servers/server/vfsreplicationnotification/class
    Description: Optional replication notification class. See Replication Notification.
  • Element: /opencms/replication/servers/server/drivers
    Description: An optional element containing the configuration of the database drivers for the replication server. See the section Replication between multiple database providers.
  • Element: /opencms/replication/servers/server/drivers/history
    Description: The element containing the configuration of the history driver for this server.
    See the section Replication between multiple database providers.
  • Element: /opencms/replication/servers/server/drivers/project
    Description: The element containing the configuration of the project driver for this server.
    See the section Replication between multiple database providers.
  • Element: /opencms/replication/servers/server/drivers/user
    Description: The element containing the configuration of the user driver for this server.
    See the section Replication between multiple database providers.
  • Element: /opencms/replication/servers/server/drivers/vfs
    Description: The element containing the configuration of the VFS driver for this server.
    See the section Replication between multiple database providers.
  • Element: /opencms/replication/servers/server/sources
    Description: A list of names of replication sets of resources, defining which resources will be replicated to this server. See next section.
  • Element: /opencms/replication/servers/server/sources/source
    Description: A name of replication sets of resources.

A list of server group definitions. A server group can be selected in the user interface for manual replication as if it were a single server. When selected for replication, the resources to be replicated will be replicated to each server matching the server group’s pattern. The order in which the servers of a group are replicated to is determined by the order in which the servers are defined in the configuration. Please note that all servers of a server group must share the same <origin> and <sources> configuration, and must be set to manual replication.

  • Element: /opencms/replication/server-groups/server-group/name
    Description: The element containing the name of the server group.
  • Element: /opencms/replication/server-groups/server-
    group/description
    Description: The element containing the description of the server group.
  • Element: /opencms/replication/server-groups/server-group/server-match
    Description: This element contains a regular expression that is applied to server names
    to determine which servers are part of the group.
  • Element: /opencms/replication/server-groups/server-group/continue-on-error
    Description: This element can contain the values “true” or “false”. When set to “false”,
    replication for a server group will stop if an error occurs during replication to any server
    of the group. When set to “true”, after an error the next server in the group will be tried.
    The element is optional; if it is omitted, a value of “true” is assumed.

A replication source or set of resources, determines what to replicate. Every replication source has to be configured in the configuration file, under a separated /opencms/replication/replicationsources/replicationsource node, which has the following structure:

  • Element: /opencms/replication/replicationsources/replicationsource
    Description: A replication source definition.
  • Element: /.../replicationsource/name
    Description: A unique name to identify the defined source, to be use in the definition of a
    replication server as described in the previous section.
  • Element: /.../replicationsource/resources
    Description: A list of resource names to be part of this replication set, if a folder all the
    subtree is included.
  • Element: /.../replicationsource/resources/resource
    Description: A resource name.

The user synchronization configuration specifies from which replication instances the users should be synchronized and which groups and organizational units should be considered (Note that user/group changes on the master are automatically transferred to the slave databases if replication is set up correctly; the user synchronization configuration feature discussed here is about the other direction, from slave database to master database).

A class for the user synchronization has to be set. This class is responsible for the comparison and conflict resolving between the user on the workplace server and the user on the replication server:

  • Element: /opencms/replication/userreplications/synchronization
    Description: The class which handles the user comparison.

Every user synchronization has to be configured in the configuration file, under a separated /opencms/replication/userreplications/userreplication node, which has the following structure:

  • Element: /opencms/replication/userreplications/userreplication
    Description: A user synchronization definition.
    • Attribute: /.../userreplications/userreplication/@name
      Description: Optional name, to be used in the scheduled job.
  • Element: /.../userreplication/server-name
    Description: The name of the replication server of this user synchronization. Should be
    the same than specified in the ocee-cluster.xml and opencms.properties
    configuration files.
  • Element: /.../userreplication/poolurl
    Description: The database pool URL, something like: opencms:replication, this
    should be same as configured ${REPLICATION_NAME} of section Master OpenCms
    Instance Installation.
  • Element: /.../userreplication/groups
    Description: The list of groups which should be considered by this user synchronization.
  • Element: /.../userreplication/groups/group
    Description: The name of the group.
  • Element: /.../userreplication/orgunits
    Description: The list of organizational units which should be considered by this user
    synchronization.
  • Element: /.../userreplication/orgunits/orgunit
    Description: The name of the organizational unit.

Sample configuration

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE opencms SYSTEM "http://www.alkacon.com/dtd/6.0/ocee-replication.dtd">
<opencms>
    <replication>
        <managersgroup>Administrators</managersgroup>
        <handlers>
            <handler>
                <class>org.opencms.ocee.replication.CmsReplicationAccountsHandler</class>
            </handler>
            <handler>
                <class>org.opencms.ocee.replication.CmsReplicationVfsHandler</class>
            </handler>
        </handlers>
        <servers>
            <server mode="auto">
                <name>Replication</name>
                <description>Description of the replication</description>
                <origin>
                    <server-name>Master</server-name>
                    <poolurl>opencms:default</poolurl>
                </origin>
                <destination>
                    <server-name>Replicated</server-name>
                    <poolurl>opencms:replication</poolurl>
                </destination>
                <vfsreplicationnotification>
                    <class>org.example.ReplicationNotification</class>
                </vfsreplicationnotification>
                <sources>
                    <source>default</source>
                </sources>
            </server>
        </servers>
        <replicationsources>
            <replicationsource>
                <name>default</name>
                <resources>
                    <resource>/sites/internet/</resource>
                    <resource>/system/categories/</resource>
                    <resource>/system/galleries/pics/</resource>
                    <resource>/system/galleries/downloads/</resource>
                    <resource>/system/modules/</resource>
                    <resource>/system/shared/</resource>
                    <resource>/system/orgunits/</resource>
                </resources>
            </replicationsource>
        </replicationsources>
        <replicationorder>
            <resource>/system/orgunits/</resource>
            <resource>/system/</resource>
            <resource>/sites/</resource>
        </replicationorder>
        <userreplications>
            <synchronization class="org.opencms.ocee.replication.CmsReplicationUserDefaultSynchronization" />
            <userreplication name="users">
                <server-name>Replicated</server-name>
                <poolurl>opencms:replication</poolurl>
                <groups>
                    <group>Users</group>
                </groups>
            </userreplication>
        </userreplications>
    </replication>
</opencms>

It is possible to configure a replication notification interface for each replication server. The class to configure needs to implement the org.opencms.ocee.replication.I_CmsReplicationNotifier interface:

/**
* Implement this interface to be called before the PUBLISH_PROJECT event gets fired after a
* replication and after the event was fired.<p>
*
* @since 3.0.2
*/
public interface I_CmsReplicationNotifier {
    /**
    * Called before the PUBLISH_PROJECT event gets propagated to the remote servers.<p>
    *
    * @param cms the current cms context
    * @param report the replication report
    * @param server the remote server
    * @param publishHistoryId the publish history id of the current replication
    */
    void beforeEventNotification(
        org.opencms.file.CmsObject cms,
        org.opencms.report.I_CmsReport report,
        org.opencms.ocee.replication.CmsReplicationServer server,
        org.opencms.util.CmsUUID publishHistoryId);


    /**
    * Called after the PUBLISH_PROJECT event was propagated to the remote servers.<p>
    *
    * @param cms the current cms context
    * @param report the replication report
    * @param server the remote server
    * @param publishHistoryId the publish history id of the current replication
    */
    void afterEventNotification(
        org.opencms.file.CmsObject cms,
        org.opencms.report.I_CmsReport report,
        org.opencms.ocee.replication.CmsReplicationServer server,
        org.opencms.util.CmsUUID publishHistoryId);
}

This interface allows to trigger functions before or after the replication notifies the remote server of the current replication process.

The replication module fires events when starting and ending the manual or automatic replication process. To add one or more classes listening to the events, you have to add a module parameter to the replication module configuration.

If the listening class should be executed on the master installation, the module parameter has to be set in the module configuration in the Administration view of OpenCms. If the execution should be started on the other servers, the opencms-modules.xml configuration files of these servers have to contain the replication module node together with the correct module parameter.

The name of the module parameter to configure is eventclasses. The specified classes have to implement the org.opencms.main.I_CmsEventListener interface and can listen to the following events:

  • org.opencms.ocee.cluster.CmsClusterEventTypes.EVENT_REPLICATION_START :
    Event that is fired on replication start.
  • org.opencms.ocee.cluster.CmsClusterEventTypes.EVENT_REPLICATION_END :
    Event that is fired on replication end

For both events the following data is set:

  • originServer: The name of the origin (source) server for the replication the event was fired.
  • destinationServer: The name of destination server for the replication the event was fired.

Currently, the OCEE replication module contains one class to start a full static export after a replication. To activate the full static export, set the following module parameter in the org.opencms.ocee.base module:

replication-eventclasses=org.opencms.ocee.replication.CmsReplicationEventStaticExport

To get a log output for the static export process, the log level for the export class has to be set to INFO in the file log4j.properties, which is located in the folder
${OPENCMS_HOME}/WEB-INF/classes/:

Note that the module parameter requires a restart to take effect.

# Set levels for all default channels available in OpenCms
...
log4j.logger.org.opencms.ocee.replication.CmsReplicationEventStaticExport=INFO

The reports of the full static export will then be written to the ${OPENCMS_HOME}/WEB-NF/logs/opencms.log  file.

The normal case when using the OCEE Replicator is that each database is using the same database product. But it is also possible to replicate between different database products with some additional configuration steps. For example, you can replicate from a master server using MySQL to a slave server using IBM DB2. To do this, you need to add a drivers node with the driver configuration to each replication server in your the opencms-replication.xml configuration file which uses a different database engine than your workplace server.

The following is an example configuration file using replication between different database providers. In a real configuration file, you need to insert the correct value for the database engine which your replication server uses instead of the placeholder ${db}. The following values for ${db} are supported:

  • mysql
  • postgresql
  • as400
  •  db2
  • hsqldb
  • mssql
  • oracle (for Oracle version 9 or higher)
  • oracle8 (for Oracle version 8)

 

Replication between different database providers

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE opencms SYSTEM "http://www.alkacon.com/dtd/6.0/ocee-replication.dtd">
<opencms>
    <replication>
        <managersgroup>Administrators</managersgroup>
        <handlers>
            <handler>
                <class>org.opencms.ocee.replication.CmsReplicationAccountsHandler</class>
            </handler>
            <handler>
                <class>org.opencms.ocee.replication.CmsReplicationVfsHandler</class>
            </handler>
        </handlers>
        <servers>
            <server mode="auto">
                <name>Replication</name>
                <description>Description of the replication</description>
                <origin>
                    <server-name>Master</server-name>
                    <poolurl>opencms:default</poolurl>
                </origin>
                <destination>
                    <server-name>Replicated</server-name>
                    <poolurl>opencms:replication</poolurl>
                </destination>
                <drivers>
                    <history class="org.opencms.db.${db}.CmsHistoryDriver" sqlmanager="org.opencms.ocee.replication.db.${db}.CmsSqlManager" />
                    <project class="org.opencms.db.${db}.CmsProjectDriver" sqlmanager="org.opencms.ocee.replication.db.${db}.CmsSqlManager" />
                    <user class="org.opencms.db.${db}.CmsUserDriver" sqlmanager="org.opencms.ocee.replication.db.${db}.CmsSqlManager" />
                    <vfs class="org.opencms.db.${db}.CmsVfsDriver" sqlmanager="org.opencms.ocee.replication.db.${db}.CmsSqlManager" />
                </drivers>
                <sources>
                    <source>default</source>
                </sources>
            </server>
        </servers>
        <replicationsources>
            <replicationsource>
                <name>default</name>
                <resources>
                    <resource>/sites/internet/</resource>
                    <resource>/system/categories/</resource>
                    <resource>/system/galleries/pics/</resource>
                    <resource>/system/galleries/downloads/</resource>
                    <resource>/system/modules/</resource>
                    <resource>/system/shared/</resource>
                    <resource>/system/orgunits/</resource>
                </resources>
            </replicationsource>
        </replicationsources>
        <replicationorder>
            <resource>/system/orgunits/</resource>
            <resource>/system/</resource>
            <resource>/sites/</resource>
        </replicationorder>
        <userreplications>
            <synchronization class="org.opencms.ocee.replication.CmsReplicationUserDefaultSynchronization" />
            <userreplication name="users">
                <server-name>Replicated</server-name>
                <poolurl>opencms:replication</poolurl>
                <groups>
                    <group>Users</group>
                </groups>
            </userreplication>
        </userreplications>
    </replication>
</opencms>