Chapter 7. Administration

Table of Contents

7.1. Changing Triggers
7.2. Changing Configuration
7.3. Sync Triggers Job
7.4. Enabling and Disabling Synchronization
7.5. Java Management Extensions
7.6. Opening Registration
7.7. Viewing Batches
7.8. Statistics
7.9. Clustering
7.10. Running as a Windows Service
7.11. Running as a Unix Service

7.1. Changing Triggers

A trigger row may be updated using SQL to change a synchronization definition. SymmetricDS will look for changes each night or whenever the Sync Triggers Job is run (see next section). For example, a change to place the table price_changes into the price channel would be accomplished with the following statement:

update SYM_TRIGGER
set channel_id = 'price',
    last_updated_by = 'jsmith',
    last_updated_time = current_timestamp
where source_table_name = 'price_changes';

The Trigger entry can be inactivated, which would drop the triggers (and any functions used by them) from the database. For example, dropping all the triggers used by the client node group would be accomplished with the following statement:

update SYM_TRIGGER
set inactive_time = current_timestamp,
    last_updated_by = 'jsmith',
    last_updated_time = current_timestamp
where source_node_group_id = 'client';

All configuration should be managed centrally at the registration node. If enabled, configuration changes will be synchronized out to client nodes. When trigger changes reach the client nodes the Sync Triggers process will run automatically.

Centrally, the trigger changes will not take effect until the Sync Triggers Job runs. Instead of waiting for the Sync Triggers Job to run overnight after making a Trigger change, invoke the syncTriggers() method over JMX or simply restart the SymmetricDS server.

7.2. Changing Configuration

The configuration of the your system as defined in the sym_* tables may be modified at runtime. By default any changes made to the sym_* tables (with the exception of sym_node) should be made at the registration server. The changes will be synchronized out to the leaf nodes by SymmetricDS triggers that are automatically created on the tables.

If this behavior is not desired, the feature can be turned off using a parameter. Custom triggers may be added to the sym_* tables when the auto syncing feature is disabled.

7.3. Sync Triggers Job

SymmetricDS examines the current configuration, corresponding database triggers, and the underlying tables to determine if database triggers need created or updated. The change activity is recorded on the Trigger Hist table with a reason for the change. The following reasons for a change are possible:

  • N - New trigger that has not been created before

  • S - Schema changes in the table were detected

  • C - Configuration changes in Trigger

  • T - Trigger was missing

A configuration entry in Trigger without any history in Trigger Hist results in a new trigger being created (N). The Trigger Hist stores a hash of the underlying table, so any alteration to the table causes the trigger to be rebuilt (S). When the last_updated_time is changed on the Trigger entry, the configuration change causes the trigger to be rebuilt (C). If an entry in Trigger Hist is missing the corresponding database trigger, the trigger is created (T).

The process of examining triggers and rebuilding them is automatically run during startup and each night by the SyncTriggersJob. The user can also manually run the process at any time by invoking the syncTriggers() method over JMX. The SyncTriggersJob is enabled by default to run at 15 minutes past midnight. If SymmetricDS is being run from a collection of servers (multiple instances of the same Node running against the same database), then locking should be enable to prevent database contention. The following runtime properties control the behavior of the process.

start.synctriggers.job

Whether the sync triggers job is enabled for this node. [ Default: true ]

job.synctriggers.aftermidnight.minutes

If scheduled, the sync triggers job will run nightly. This is how long after midnight that job will run. [ Default: 15 ]

cluster.lock.during.sync.triggers

Indicate if the sync triggers job is clustered and requires a lock before running. [ Default: false ]

7.4. Enabling and Disabling Synchronization

7.5. Java Management Extensions

Monitoring and administrative operations can be performed using Java Management Extensions (JMX). SymmetricDS uses MX4J to expose JMX attributes and operations that can be accessed from the built-in web console, Java's jconsole, or an application server. By default, the web management console can be opened from the following address:

http://localhost:31416/

Using the Java jconsole command, SymmetricDS is listed as a local process named SymmetricLauncher. In jconsole, SymmetricDS appears under the MBeans tab as DefaultDomain.

The management interfaces under DefaultDomain are organized as follows:

  • Node - administrative operations

  • Incoming - statistics about incoming batches

  • Outgoing - statistics about outgoing batches

  • Parameters - access to properties set through the parameter service

  • Notifications - setting thresholds and receiving notifications

7.6. Opening Registration

7.7. Viewing Batches

7.8. Statistics

7.9. Clustering

A single SymmetricDS node may be clustered across a series of instances, creating a web farm. A node might be clustered to provide load balancing and failover, for example.

When clustered, a hardware load balancer is typically used to round robin client requests to the cluster. The load balancer should be configured for stateless connections. Also, the sync.url SymmetricDS property should be set to the URL of the load balancer.

If the cluster will be running any of the SymmetricDS jobs, then the following properties should be set to true.

cluster.lock.during.purge=true
cluster.lock.during.pull=true
cluster.lock.during.push=true
cluster.lock.during.heartbeat=true
cluster.lock.during.sync.triggers=true

By setting these properties to true, SymmetricDS will use a row in the SYM_LOCK table as a semaphore to make sure that only one instance at a time runs a job. When a lock is acquired, a row is updated in the lock table with the time of the lock and the server id of the locking job. The lock time is set back to null when the job is finished running. Another instance of SymmetricDS cannot acquire a lock until the locking instance (according to the server id) releases the lock. If an instance is terminated while the lock is still held, an instance with the same server id is allowed to re-acquire the lock. If the locking instance remains down, the lock can be broken after a period of time, specified by the cluster.lock.timeout.ms property, has expired. Note that if the job is still running and the lock expires, two jobs could be running at the same time which could cause database deadlocks.

By default, the locking server id is the hostname of the server. If two clustered instances are running on the same server, then the cluster.server.id property may be set to indicate the name that the instance should use for its server id.

When deploying SymmetricDS to an application server like Tomcat or JBoss, no special session clustering needs to be configured for the application server.

7.10. Running as a Windows Service

SymmetricDS uses a Java service wrapper called JavaService in order to run in the background as a Windows NT/2000/XP system service. The JavaService executable is named sym_service.exe so it can be easily identified from a list of running processes. To install the service, use the provided script:

bin\install_service.bat

The script contains configuration that can be changed, including the server port number and file locations. The server defaults to port 8080. It will look in the conf directory for the symmetric.properties file and the log4j.xml file. Logging for standard out, error, and application are written to the logs directory.

When the configuration is changed, the service should be un-installed and then installed again. To un-install the service, use the provided script:

bin\uninstall_service.bat

Use the net command to start and stop the service:

net start symmetric

net stop symmetric

7.11. Running as a Unix Service

SymmetricDS uses an init script in order to run in the background as a Unix service (also called a daemon). The symmetric.init file follows the Linux Standard Base specification, which should work on many systems, including Fedora and Debian. To install the script, copy it into the system init directory:

cp bin/symmetric.init /etc/init.d/symmetric

Edit the init script to set the SYM_HOME variable to the directory where SymmetricDS is located. The init script calls the sym_service script, which contains configuration such as port number and file locations. The server defaults to port 8080. It will look in the conf directory for the symmetric.properties file and the log4j.xml file. Logging for standard out, error, and application are written to the logs directory.

To enable the service to run automatically when the system is started:

/sbin/chkconfig --add symmetric

To disable the service from running automatically:

/sbin/chkconfig --del symmetric

Use the service command to start, stop, and query the status of the service:

/sbin/service symmetric start

/sbin/service symmetric stop

/sbin/service symmetric status