Chapter 5. Advanced Topics

Table of Contents

5.1. Advanced Synchronization
5.1.1. Bi-Directional Synchronization
5.1.2. Multi-Tiered Synchronization Registration Redirect
5.2. Jobs
5.2.1. Route Job Overview Data Gaps
5.2.2. Controlling Synchronization Frequency
5.2.3. Sync Triggers Job
5.3. JMS Publishing
5.4. Deployment Options
5.4.1. Web Archive
5.4.2. Standalone
5.4.3. Embedded
5.5. Running SymmetricDS as a Service
5.5.1. Running as a Windows Service
5.5.2. Running as a *nix Service
5.6. Clustering
5.7. Encrypted Passwords
5.8. Secure Transport
5.8.1. Sym Launcher
5.8.2. Tomcat
5.8.3. Keystores
5.8.4. Generating Keys
5.9. Basic Authentication
5.10. IP Filtering
5.10.1. CIDR Filter
5.10.2. Literal Filter
5.10.3. Wildcarding
5.10.4. Range Filters
5.10.5. Inner workings
5.10.6. Configuration

This chapter focuses on a variety of topics, including deployment options, jobs, clustering, encryptions, synchronization control, and configuration of SymmetricDS.

5.1. Advanced Synchronization

5.1.1. Bi-Directional Synchronization

SymmetricDS allows tables to be synchronized bi-directionally. Note that an outgoing synchronization does not process changes during an incoming synchronization on the same node unless the trigger was created with the sync_on_incoming_batch flag set. If the sync_on_incoming_batch flag is set, then update loops are prevented by a feature that is available in most database dialects. More specifically, during an incoming synchronization the source node_id is put into a database session variable that is available to the database trigger. Data events are not generated if the target node_id on an outgoing synchronization is equal to the source node_id.

By default, only the columns that changed will be updated in the target system.

More complex conflict resolution strategies can be accomplished by using the IDataLoaderFilter extension point which has access to both old and new data.

5.1.2. Multi-Tiered Synchronization

As shown in Section 3.2, “Organizing Nodes”, there may be scenarios where data needs to flow through multiple tiers of nodes that are organized in a tree-like network with each tier requiring a different subset of data. For example, you may have a system where the lowest tier may by a computer or device located in a store. Those devices may connect to a server located physically at that store. Then the store server may communicate with a corporate server for example. In this case, the three tiers would be device, store, and corporate. Each tier is typically represented by a node group. Each node in the tier would belong to the node group representing that tier.

A node will always push and pull data to other node groups according to the node group link configuration. A node can only pull and push data to other nodes that are represented node table in its database and having sync_enabled = 1. Because of this, a tree-like hierarchy of nodes can be created by having only a subset of nodes belonging to the same node group represented at the different branches of the tree.

If auto registration is turned off, then this setup must occur manually by opening registration for the desired nodes at the desired parent node and by configuring each node's registration.url to be the parent node's URL. The parent node is always tracked by the setting of the parent's node_id in the created_at_node_id column of the new node. When a node registers and downloads its configuration it is always provided the configuration for nodes that might register with the node itself based on the Node Group Links defined in the parent node. Registration Redirect

When deploying a multi-tiered system it may be advantageous to have only one registration server, even though the parent node of a registering node could be any of a number of nodes in the system. In SymmetricDS the parent node is always the node that a child registers with. The REGISTRATION_REDIRECT table allows a single node, usually the root server in the network, to redirect registering nodes to their true parents. It does so based on a mapping found in the table of the external id (registrant_external_id) to the parent's node id (registration_node_id).

For example, if it is desired to have a series of regional servers that workstations at retail stores get assigned to based on their external_id, the store number, then you might insert into REGISTRATION_REDIRECT the store number as the registrant_external_id and the node_id of the assigned region as the registration_node_id. When a workstation at the store registers, the root server send an HTTP redirect to the sync_url of the node that matches the registration_node_id.


Please see Section, “Initial Load” for important details around initial loads and registration when using registration redirect.

5.2. Jobs

The SymmetricDS software allows for outgoing and incoming changes to be synchronized to/from other databases. The node that initiates a synchronization connection is the client, and the node receiving a connection is the host. Because synchronization is configurable to push or pull in either direction, the same node can act as either a client or a host in different circumstances.

The SymmetricDS software consists of a series of background jobs, managers, Servlets, and services wired together via dependency injection using the Spring Framework.

As a client, the node runs the router job, push job and pull job on a timer thread. The router job uses services to create batches that are targeted at certain nodes. The push job uses services to extract and stream data to another node (that is, it pushes data). The response from a push is a list of batch acknowlegements to indicate that data was loaded. The pull job uses services to load data that is streamed from another node (i.e., it pulls data). After loading data, a second connection is made to send a list of batch acknowlegements.

As a host, the node waits for incoming connections that pull, push, or acknowledge data changes. The push Servlet uses services to load data that is pushed from a client node. After loading data, it responds with a list of batch acknowledgements. The pull Servlet uses services to extract, and stream data back to the client node. The ack Servlet uses services to update the status of data that was loaded at a client node. The router job batches and routes data.

By default, data is extracted from the source database into memory until a threshold size is reached. If the threshold size is reached, data is streamed to a temporary file in the JVM's default temporary directory. Next, the data is streamed to the target node across the transport layer. The receiving node will cache the data in memory until the threshold size is reached, writing to a temporary file if necessary. At last, the data is loaded into the target database by the data loader. This step by step approach allows for extract time, transport time, and load time to all be measured independently. It also allows database resources to be used most optimally.

The transport manager handles the incoming and outgoing streams of data between nodes. The default transport is based on a simple implementation over HTTP. An internal transport is also provided. It is possible to add other implementations, such as a socket-based transport manager.

Node communication over HTTP is represented in the following figure.

Node Communication

Figure 5.1. Node Communication

The StandaloneSymmetricEngine is wrapper API that can be used to directly start the client services only. The SymmetricWebServer is a wrapper API that can be used to directly start both the client and host services inside a Jetty web container. The SymmetricLauncher provides command line tools to work with and start SymmetricDS.

5.2.1. Route Job Overview

The SymmetricDS-created database triggers cause data to be capture in the DATA table. The next step in the synchronization process is to process the change data to determine which nodes, if any, the data should be routed to. This step is performed by the Route Job. In addition to determining which nodes data will be sent to, the Route Job is also responsible for determing how much data will be batched together for transport. It is a single background task that inserts into DATA_EVENT and OUTGOING_BATCH.

At a high level, the Route Job is straightforward. It collects a list of data ids from DATA which haven't yet been routed (see Section, “Data Gaps” for much more detail about this step), one channel at a time, up to a limit specified by the channel configuration (max_data_to_route, on CHANNEL). The data is then batched based on the batch_algorithm defined for the channel and as documented in Section 4.5, “Channel”. Note that, for the default batching algorithm, there may actually be more than max_data_to_route included depending on the transaction boundaries. The mapping of data to specific nodes, organized into batches, is then recorded in OUTGOING_BATCH with a status of "RT" in each case (representing the fact that the Route Job is still running). Once the routing algorithms and batching are completed, the batches are organized with their corresponding data ids and saved in DATA_EVENT. Once DATA_EVENT is updated, the rows in OUTGOING_BATCH are updated to a status of New "NE". Data Gaps

On the surface, the first Route Job step of collecting unrouted data ids seems simple: assign sequential data ids for each data row as it's inserted and keep track of which data id was last routed and start from there. The difficulty arises, however, due to the fact that there can be multiple transactions inserting into DATA simultaneously. As such, a given section of rows in the DATA table may actually contain "gaps" in the data ids when the Route Job is executing. Most of these gaps are only temporarily and fill in at some point after routing and need to be picked up with the next run of the Route Job. Thus, the Route Job needs to remember to route the filled-in gaps. Worse yet, some of these gaps are actually permanent and result from a transaction that is rolled back for some reason. In this case, the Route Job must continue to watch for the gap to fill in and, at some point, eventually gives up and assumes the gap is permanent and can be skipped. All of this must be done in some fashion that guarantees that gaps are routed when they fill in while also keeping routing as efficient as possible.

SymmetricDS handles the issue of data gaps by making use of a table, DATA_GAP, to record gaps found in the data ids. In fact, this table completely defines the entire range of data tha can be routed at any point in time. For a brand new instance of SymmetricDS, this table is empty and SymmetricDS creates a gap starting from data id of zero and ending with a very large number (defined by At the start of a Route Job, the list of valid gaps (gaps with status of 'GP') is collected, and each gap is evaluated in turn. If a gap is sufficiently old (as defined by, the gap is marked as skipped (status of 'SK') and will no longer be evaluated in future Route Jobs (note that the 'last' gap (the one with the highest starting data id) is never skipped). If not skipped, then DATA_EVENT is searched for data ids present in the gap. If one or more data ids is found in DATA_EVENT, then the current gap is marked with a status of OK, and new gap(s) are created to represent the data ids still missing in the gap's range. This process is done for all gaps. If the very last gap contained data, a new gap starting from the highest data id and ending at (highest data id + is then created. This process has resulted in an updated list of gaps which may contain new data to be routed.

5.2.2. Controlling Synchronization Frequency

The frequency of data synchronization is controlled by the coordination of a series of asynchronous events.

The Route Job determines which nodes data will be sent to, as well as how much data will be batched together for transport. When the start.route.job SymmetricDS property is set to true, the frequency that routing occurs is controlled by the Each time data is routed, the DATA_REF table is updated with the id of the last contiguous data row to have been processed. This is done so the query to find unrouted data is optimal.

After data is routed, it awaits transport to the target nodes. Transport can occur when a client node is configured to pull data or when the host node is configured to push data. These events are controlled by the Push and the Pull Jobs. When the start.pull.job SymmetricDS property is set to true, the frequency that data is pulled is controlled by the When the start.push.job SymmetricDS property is set to true, the frequency that data is pushed is controlled by the Data is extracted by channel from the source database's DATA table at an interval controlled by the extract_period_millis column on the CHANNEL table. The last_extract_time is always recorded, by channel, on the NODE_CHANNEL_CTL table for the host node's id. When the Pull and Push Job run, if the extract period has not passed according to the last extract time, then the channel will be skipped for this run. If the extract_period_millis is set to zero, data extraction will happen every time the jobs run.

SymmetricDS also provides the ability to configure windows of time when synchronization is allowed. This is done using the NODE_GROUP_CHANNEL_WINDOW table. A list of allowed time windows can be specified for a node group and a channel. If one or more windows exist, then data will only be extracted and transported if the time of day falls within the window of time specified. The configured times are always for the target node's local time. If the start_time is greater than the end_time, then the window crosses over to the next day.

All data loading may be disabled by setting the dataloader.enable property to false. This has the effect of not allowing incoming synchronizations, while allowing outgoing synchronizations. All data extractions may be disabled by setting the dataextractor.enable property to false. These properties can be controlled by inserting into the root server's PARAMETER table. These properties affect every channel with the exception of the 'config' channel.

5.2.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_update_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.


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


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


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

5.3. JMS Publishing

With the proper configuration SymmetricDS can publish XML messages of captured data changes to JMS during routing or transactionally while data loading synchronized data into a target database. The following explains how to publish to JMS during synchronization to the target database.

The XmlPublisherDataLoaderFilter is a IDataLoaderFilter that may be configured to publish specific tables as an XML message to a JMS provider. See Chapter 6, Extending SymmetricDS for information on how to configure an extension point. If the publish to JMS fails, the batch will be marked in error, the loaded data for the batch will be rolled back and the batch will be retried during the next synchronization run.

The following is an example extension point configuration that will publish four tables in XML with a root tag of 'sale'. Each XML message will be grouped by the batch and the column names identified by the groupByColumnNames property which have the same values.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns=""
    <bean id="configuration-publishingFilter" 
        <property name="xmlTagNameToUseForGroup" value="sale"/>
        <property name="tableNamesToPublishAsGroup">
        <property name="groupByColumnNames">
        <property name="publisher">
           <bean class="org.jumpmind.symmetric.integrate.SimpleJmsPublisher">
               <property name="jmsTemplate" ref="definedSpringJmsTemplate"/>

The publisher property on the XmlPublisherDataLoaderFilter takes an interface of type IPublisher. The implementation demonstrated here is an implementation that publishes to JMS using Spring's JMS template. Other implementations of IPublisher could easily publish the XML to other targets like an HTTP server, the file system or secure copy it to another server.

The above configuration will publish XML similiar to the following:

<?xml version="1.0" encoding="UTF-8"?>
<sale xmlns:xsi="" 
  id="0012010-01-220031234" nodeid="00001" time="1264187704155">
  <row entity="SALE_TX" dml="I">
    <data key="STORE_ID">001</data>
    <data key="BUSINESS_DAY">2010-01-22</data>
    <data key="WORKSTATION_ID">003</data>
    <data key="TRANSACTION_ID">1234</data>
    <data key="CASHIER_ID">010110</data>
  <row entity="SALE_LINE_ITEM" dml="I">
    <data key="STORE_ID">001</data>
    <data key="BUSINESS_DAY">2010-01-22</data>
    <data key="WORKSTATION_ID">003</data>
    <data key="TRANSACTION_ID">1234</data>
    <data key="SKU">9999999</data>  
    <data key="PRICE">10.00</data>
    <data key="DESC" xsi:nil="true"/>
  <row entity="SALE_LINE_ITEM" dml="I">
    <data key="STORE_ID">001</data>
    <data key="BUSINESS_DAY">2010-01-22</data>
    <data key="WORKSTATION_ID">003</data>
    <data key="TRANSACTION_ID">1234</data>
    <data key="SKU">9999999</data>  
    <data key="PRICE">10.00</data>
    <data key="DESC" xsi:nil="true"/>
  <row entity="SALE_TAX" dml="I">
    <data key="STORE_ID">001</data>
    <data key="BUSINESS_DAY">2010-01-22</data>
    <data key="WORKSTATION_ID">003</data>
    <data key="TRANSACTION_ID">1234</data>
    <data key="AMOUNT">1.33</data>  
  <row entity="SALE_TOTAL" dml="I">
    <data key="STORE_ID">001</data>
    <data key="BUSINESS_DAY">2010-01-22</data>
    <data key="WORKSTATION_ID">003</data>
    <data key="TRANSACTION_ID">1234</data>
    <data key="AMOUNT">21.33</data>  

To publish JMS messages during routing the same pattern is valid, with the exception that the extension point would be the XmlPublisherDataRouter and the router would be configured by setting the router_type of a ROUTER to the Spring bean name of the registered extension point. Of course, the router would need to be linked through TRIGGER_ROUTERs to each TRIGGER table that needs published.

5.4. Deployment Options

An instance of SymmetricDS can be deployed in several ways:

  • Web application archive (WAR) deployed to an application server

    This option means packaging a WAR file and deploying to your favorite web server, like Apache Tomcat. It's a little more work, but you can configure the web server to do whatever you need. SymmetricDS can also be embedded in an existing web application, if desired.

  • Standalone service that embeds Jetty web server

    This option means running the sym command line, which launches the built-in Jetty web server. This is a simple option because it is already provided, but you lose the flexibility to configure the web server any further.

  • Embedded as a Java library in an application

    This option means you must write a wrapper Java program that runs SymmetricDS. You would probably use Jetty web server, which is also embeddable. You could bring up an embedded database like Derby or H2. You could configure the web server, database, or SymmetricDS to do whatever you needed, but it's also the most work of the three options discussed thus far.

  • Grails Application

    A Grails SymmetricDS plugin is provided at the default Grails plugin site. This option ends up being a WAR deployment, but allows for the use of the Grails SDK for configuring and building the deployment. The plugin also provides Gorm (Hibernate) access to many of the core database tables.

The deployment model you choose depends on how much flexibility you need versus how easy you want it to be. Both Jetty and Tomcat are excellent, scalable web servers that compete with each other and have great performance. Most people choose either the Standalone or Web Archive with Tomcat 5.5 or 6. Deploying to Tomcat is a good middle-of-the-road decision that requires a little more work for more flexibility.

Next, we will go into a little more detail on the first three deployment options listed above.

5.4.1. Web Archive

As a web application archive, a WAR is deployed to an application server, such as Tomcat, Jetty, or JBoss. The structure of the archive will have a web.xml file in the WEB-INF folder, an appropriately configured file in the WEB-INF/classes folder, and the required JAR files in the WEB-INF/lib folder.

A war file can be generated using the standalone installation's sym utility and the --create-war option. The command requires the name of the war file to generate. It essentially packages up the web directory, the conf directory and includes an optional properties file. Note that if a properties file is included, it will be copied to WEB-INF/classes/ This is the same location conf/ would have been copied to. The generated war distribution uses the same web.xml as the standalone deployment.

../bin/sym -p --create-war /some/path/to/symmetric-ds.war

The web.base.servlet.path property in can be set if the SymmetricServlet needs to coexist with other Servlets. By default, the value is blank. If you set it to, say, web.base.servlet.path=sync for exmaple, registration.url would be http://server:port/sync.

5.4.2. Standalone

A standalone service can use the sym command line options to start a server. An embedded instance of Jetty is used to service web requests for all the servlets.

/symmetric/bin/sym --properties --port 8080 --server

This example starts the SymmetricDS server on port 8080 with the startup properties found in the file.

5.4.3. Embedded

A Java application with the SymmetricDS Java Archive (JAR) library on its classpath can use the SymmetricWebServer to start the server.

import org.jumpmind.symmetric.SymmetricWebServer;

public class StartSymmetricEngine {

     * Start an engine that is configured by two properties files. One is
     * packaged with the application and contains overridden properties that are
     * specific to the application. The other is found in the application's
     * working directory. It can be used to setup environment specific
     * properties.
    public static void main(String[] args) throws Exception {
        SymmetricWebServer node = new SymmetricWebServer(

        // this will create the database, sync triggers, start jobs running
        // this will stop the node


This example starts the SymmetricDS server on port 8080 with startup properies found in two locations. The first file,, is packaged in the application to provide properties that override the SymmetricDS default values.

5.5. Running SymmetricDS as a Service

SymmetricDS can be configured to start and run as a service in both Windows and *nix platforms.

5.5.1. Running as a Windows Service

SymmetricDS uses the Java Service Wrapper product from Tanuki Software to run in the background as a Windows system service. The Java Service Wrapper 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:


The service configuration is found in conf/sym_service.conf. Edit this file if you want to change the default port number (8080), initial memory size (256 MB), log file size (10 MB), or other settings. When started, the server will look in the conf directory for the file and the log4j.xml file. Logging for standard out, error, and application are written to the logs directory.

Most configuration changes do not require the service to be re-installed. To un-install the service, use the provided script:


Use the net command to start and stop the service:

net start symmetric
net stop symmetric

5.5.2. Running as a *nix Service

SymmetricDS uses the Java Service Wrapper product from Tanuki Software to run in the background as a Unix system service. The Java Service Wrapper executable is named sym_service so it can be easily identified from a list of running processes. The service configuration is found in conf/sym_service.conf. Edit this file if you want to change the default port number (8080), initial memory size (256 MB), log file size (10 MB), or other settings.

An init script is provided to work with standard Unix run configuration levels. The sym_service.initd file follows the Linux Standard Base specification, which should work on many systems, including Fedora and Debian-based distributions. To install the script, copy it into the system init directory:

cp bin/sym_service.initd /etc/init.d/sym_service

Edit the init script to set the SYM_HOME variable to the directory where SymmetricDS is located. The init script calls the sym_service executable.

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

/sbin/chkconfig --add sym_service

To disable the service from running automatically:

/sbin/chkconfig --del sym_service

On Suse Linux install the service by calling:

/usr/lib/lsb/install_initd sym_service

Remove the service by calling:

/usr/lib/lsb/remove_initd sym_service

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

/sbin/service sym_service start
/sbin/service sym_service stop
/sbin/service sym_service status

Alternatively, call the init.d script directly:

/etc/init.d/sym_service start
/etc/init.d/sym_service stop
/etc/init.d/sym_service status

5.6. 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 (discussed in Section 4.1, “Node Properties”) 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 cluster.lock.enabled property should be set to true. By setting this property to true, SymmetricDS will use a row in the 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 aquire 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 reaquire the lock. If the locking instance remains down, the lock can be broken after a period of time, specified by the 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 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.

5.7. Encrypted Passwords

The db.user and db.password properties will accept encrypted text, which protects against casual observation. The text is prefixed with enc: to indicate that it is encrypted. To encrypt text, use the following command:

sym -e secret

The text is encrypted by the cipher defined as alias "sym.secret" in the Java keystore. The keystore is specified by the "sym.keystore.file" system property, which defaults to security/keystore. If a cipher is not found, a default cipher using Triple DES with a random password is generated.

5.8. Secure Transport

By specifying the "https" protocol for a URL, SymmetricDS will communicate over Secure Sockets Layer (SSL) for an encrypted transport. The following properties need to be set with "https" in the URL:


This is the URL of the current node, so if you want to force other nodes to communicate over SSL with this node, you specify "https" in the URL.


This is the URL where the node will connect for registration when it first starts up. To protect the registration with SSL, you specify "https" in the URL.

For incoming HTTPS connections, SymmetricDS depends on the webserver where it is deployed, so the webserver must be configured for HTTPS. As a standalone deployment, the "sym" launcher command provides options for enabling HTTPS support.

5.8.1. Sym Launcher

The "sym" launch command uses Jetty as an embedded web server. Using command line options, the web server can be told to listen for HTTP, HTTPS, or both.

sym --port 8080 --server

sym --secure-port 8443 --secure-server

sym --port 8080 --secure-port 8443 --mixed-server

5.8.2. Tomcat

If you deploy SymmetricDS to Apache Tomcat, it can be secured by editing the TOMCAT_HOME/conf/server.xml configuration file. There is already a line that can be uncommented and changed to the following:

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" 
  maxThreads="150" scheme="https" secure="true" 
  clientAuth="false" sslProtocol="TLS"
  keystoreFile="/symmetric-ds-1.x.x/security/keystore" />

5.8.3. Keystores

When SymmetricDS connects to a URL with HTTPS, Java checks the validity of the certificate using the built-in trusted keystore located at JRE_HOME/lib/security/cacerts. The "sym" launcher command overrides the trusted keystore to use its own trusted keystore instead, which is located at security/cacerts. This keystore contains the certificate aliased as "sym" for use in testing and easing deployments. The trusted keystore can be overridden by specifying the system property.

When SymmetricDS is run as a secure server with the "sym" launcher, it accepts incoming requests using the key installed in the keystore located at security/keystore. The default key is provided for convenience of testing, but should be re-generated for security.

5.8.4. Generating Keys

To generate new keys and install a server certificate, use the following steps:

  1. Open a command prompt and navigate to the security subdirectory of your SymmetricDS installation.

  2. Delete the old key pair and certificate.

    keytool -keystore keystore -delete -alias sym

    keytool -keystore cacerts -delete -alias sym

    Enter keystore password:  changeit
  3. Generate a new key pair.

    keytool -keystore keystore -alias sym -genkey -keyalg RSA -validity 10950

    Enter keystore password:  changeit
    What is your first and last name?
      [Unknown]:  localhost
    What is the name of your organizational unit?
      [Unknown]:  SymmetricDS
    What is the name of your organization?
      [Unknown]:  JumpMind
    What is the name of your City or Locality?
    What is the name of your State or Province?
    What is the two-letter country code for this unit?
    Is CN=localhost, OU=SymmetricDS, O=JumpMind, L=Unknown, ST=Unknown, C=Unknown
      [no]:  yes
    Enter key password for <sym>
            (RETURN if same as keystore password):
  4. Export the certificate from the private keystore.

    keytool -keystore keystore -export -alias sym -rfc -file sym.cer

  5. Install the certificate in the trusted keystore.

    keytool -keystore cacerts -import -alias sym -file sym.cer

5.9. Basic Authentication

SymmetricDS supports basic authentication for client and server nodes. To configure a client node to use basic authentication when communicating with a server node, specify the following startup parameters:


username for client node basic authentication. [ Default: ]


password for client node basic authentication. [ Default: ]

The SymmetricDS Standalone and Embedded Server also support basic authentication. This feature is enabled by specifying the basic authentication username and password using the following startup parameters:


username for basic authentication for an embedded server or standalone server node. [ Default: ]


password for basic authentication for an embedded server or standalone server node. [ Default: ]

If the server node is deployed to Tomcat or another application server as a WAR or EAR file, then basic authentication is setup with the standard configuration in the WEB.xml file.

5.10. IP Filtering

SymmetricDS supports restricting IP addresses of clients that are allowed to connect to servers. The following filtering functionality is supported for IPv4 addresses (IPv6 is currently not supported).

  • CIDR (Classless Inter-Domain Routing) notation

  • Wildcarding

  • Range

  • Literal

5.10.1. CIDR Filter

Classless Inter-Domain Routing, CIDR, notation is the preferred notation for restricting client connections to a server node in a SymmetricDS tree. It is a commonly utilized format for IP address filtering. Many established frameworks, such as Apache, utilize this notation for filtering IP addresses.

The basis for implementing CIDR notation is defining the IP address block and significant bits of that address that are to be checked. The filter must be a well formatted IP address with a ending with a “/” followed by a numeric value between 0 and 32. The use of “0” denotes that all IP addresses are allowed (in which case it's fairly pointless to enable the filtering framework), and “32” signifies only the precesding IP address would be authorized. In the latter case, a Literal Filter string would be recommended as it is significantly more obvious that only that address is allowed.

                # Filter string definition to restrict connecting client
                # IP addresses

Example 5.1. CIDR Filter String Definition in

5.10.2. Literal Filter

Literal filter definitions are just that: they define a single IP address that is authorized to connect to the server. The only requirement is that the filter string is a complete, well formatted IP address.

5.10.3. Wildcarding

The wildcard notation allows all values for a specific piece of an IP address to be valid (0 to 255 for IPv4 addresses). This is denoted with a “*” within the specific piece (octet for IPv4) of an IP address. The wildcard character is the only allowable character within that piece of the address (no other characters included whitespace).

Wildcard filters may be combined with Range Filters. They may NOT be combined with CIDR Filter.

                # Filter string definition to restrict connecting client
                # IP addresses

Example 5.2. Wildcard Filter String Definition in

5.10.4. Range Filters

Range filter definitions allow for a numeric range to be specified within an address filter. A range must be a valid numeric range for an piece of an IP address (i.e. an octet in IPv4). The range definition must be in the form:

                # Filter string definition to restrict connecting client
                # IP addresses

Example 5.3. Filter String Definition in

5.10.5. Inner workings

Filter strings are compiled on startup, so the hit (although very small) of compiling the authorizers is incurred only once. Once compiled each request is passed through the chain of authorizers until either a authorization is passed or the chain is exhausted. In the latter case the request is denied and a protocol specific response is sent to the client. In the case of HTTP this would be a response code of 401 (FORBIDDEN).

5.10.6. Configuration

Configuring IP filter strings is done through defining the following property in the SymmetricDS configuration (one of the symmetric .properties files). One need only to define the ip.filter property and assign a comma “,” delimited string of filter tokens to provide to the filter framework.

                # Filter string definition to restrict connecting client
                # IP addresses
                ip.filters=, 100.50-40.10-5.*,

Example 5.4. Filter String Definition in


Note, that there is obvious overlap between the some of the filtering notation, and hence, functionality. The Wildcarding and Range Filters functionality exists to provide workarounds for scenarios where CIDR Filter notation and Literal Filter will not suffice.


Take care in defining your filter string as it is possible to overlap filters. Also, as with the definition of any other property in the SymmetricDS configuration, if the property is defined in multiple properties files the property file that is read in last will override any previous filter string definitions.