Appendix B. Parameters

There are two kinds of parameters that can be used to configure the behavior of SymmetricDS: Startup Parameters and Runtime Parameters . Startup Parameters are required to be in a system property or a property file, while Runtime Parameters can also be found in the Parameter table from the database. Parameters are re-queried from their source at a configured interval and can also be refreshed on demand by using the JMX API. The following table shows the source of parameters and the hierarchy of precedence.

LocationRequiredDescription
symmetric-default.properties Y Packaged inside symmetric-core jar file. This file has all the default settings along with descriptions.
conf/symmetric.properties N Changes to this file in the conf directory of a standalone install apply to all engines in the JVM.
symmetric-override.properties NChanges to this file, provided by the end user in the JVM's classpath, apply to all engines in the JVM.
engines/*.properties N Properties for a specific engine or node that is hosted in a standalone install.
Java System Properties N Any SymmetricDS property can be passed in as a -D property to the runtime. It will take precedence over any properties file property.
Parameter table N A table which contains SymmetricDS parameters. Parameters can be targeted at a specific node group and even at a specific external id. These settings will take precedence over all of the above.
IParameterFilter N An extension point which allows parameters to be sourced from another location or customized. These settings will take precedence over all of the above.

Table B.1. Parameter Locations


B.1. Startup Parameters

Startup parameters are read once from properties files and apply only during start up. The following properties are used:

engine.name

This is the engine name. This should be set if you have more than one engine running in the same JVM. It is used to name the JMX management bean. [ Default: Default ]

registration.url

The URL where this node can connect for registration to receive its configuration. This property is only valid if you use the default IRuntimeConfiguration implementation. [ Default: ]

sync.url

The URL where this node can be contacting for synchronization. [ Default: http://localhost:8080/sync ]

group.id

The node group id for this node. [ Default: default ]

external.id

The secondary identifier for this node that has meaning to the system where it is deployed. While the node id is a generated sequence number, the external ID could have meaning in the user's domain, such as a retail store number. [ Default: ]

db.driver

The class name of the JDBC driver. If db.jndi.name is set, this property is ignored. [ Default: com.mysql.jdbc.Driver ]

db.url

The JDBC URL used to connect to the database. If db.jndi.name is set, this property is ignored. [ Default: jdbc:mysql://localhost/symmetric ]

db.user

The database username, which is used to login, create, and update SymmetricDS tables. To use an encrypted username, see Section 5.7, “Encrypted Passwords” . If db.jndi.name is set, this property is ignored. [ Default: symmetric ]

db.password

The password for the database user. To use an encrypted password, see Section 5.7, “Encrypted Passwords” . If db.jndi.name is set, this property is ignored. [ Default: ]

db.pool.initial.size

The initial size of the connection pool. If db.jndi.name is set, this property is ignored. [ Default: 5 ]

db.pool.max.active

The maximum number of connections that will be allocated in the pool. If db.jndi.name is set, this property is ignored. [ Default: 10 ]

db.pool.max.wait.millis

This is how long a request for a connection from the datasource will wait before giving up. If db.jndi.name is set, this property is ignored. [ Default: 30000 ]

db.pool.min.evictable.idle.millis

This is how long a connection can be idle before it will be evicted. If db.jndi.name is set, this property is ignored. [ Default: 120000 ]

db.sql.query.timeout.seconds

The timeout in seconds for queries running on the database. [ Default: 300 ]

db.jdbc.streaming.results.fetch.size

This is the default fetch size for streaming result sets into memory from the database. [ Default: 1000 ]

auto.config.database

If this is true, the configuration and runtime tables used by SymmetricDS are automatically created during startup. [ Default: true ]

auto.sync.configuration

If this is true, create triggers for the SymmetricDS configuration table that will synchronize changes to node groups that pull from the node where this property is set. [ Default: true ]

https.allow.self.signed.certs

If this is true, a Symmetric client node to accept self signed certificates. [ Default: true ]

http.basic.auth.username

If specified, a Symmetric client node will use basic authentication when communicating with its server node using the given user name. [ Default: ]

http.basic.auth.password

If specified, the password used for basic authentication. [ Default: ]

https.verified.server.names

A list of comma separated server names that will always verify when using https. This is useful if the URL's hostname and the server's identification hostname don't match exactly using the default rules for the JRE. A special value of "all" may be specified to allow all hostnames to verify. [ Default: ]

sync.table.prefix

When symmetric tables are created and accessed, this is the prefix to use for the table name. [ Default: sym ]

start.route.job

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

job.route.period.time.ms

This is how often the route job will be run if enabled. [ Default: 10000 ]

start.push.job

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

job.push.period.time.ms

This is how often the push job will be run if enabled. [ Default: 60000 ]

start.pull.job

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

job.pull.period.time.ms

This is how often the pull job will be run if enabled. [ Default: 60000 ]

start.purge.job

Whether the purge jobs are enabled for this node. [ Default: true ]

job.purge.incoming.cron

This is how often the incoming batch purge job will be run if enabled. [ Default: 0 0 0 * * * ]

job.purge.outgoing.cron

This is how often the outgoing batch and data purge job will be run if enabled. [ Default: 0 0 0 * * * ]

job.purge.datagaps.cron

This is how often the data gaps purge job will be run if enabled. [ Default: 0 0 0 * * * ]

start.synctriggers.job

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

job.synctriggers.cron

This is how often the sync triggers job will be run if enabled. [ Default: 0 0 0 * * * ]

start.stage.management.job

Whether the stage directory management/purge job is enabled for this node. [ Default: true ]

job.stage.management.period.time.ms

This is how often the stage management job will be run if enabled. [ Default: 15000 ]

start.stat.flush.job

Whether the statistics flush (to database) job is enabled for this node. [ Default: true ]

job.stat.flush.cron

This is how often accumulated statistics will be flushed out to the database from memory. [ Default: 0 0/5 * * * * ]

start.heartbeat.job

Whether the heartbeat job is enabled for this node. The heartbeat job simply inserts an event to update the heartbeat_time column on the node table for the current node. [ Default: true ]

job.heartbeat.period.time.ms

This is how often the heartbeat job runs. Note that this doesn't mean that a heartbeat is performed this often. See heartbeat.sync.on.push.period.sec to change how often the heartbeat is sync'd. [ Default: 1000 ]

heartbeat.sync.on.push.period.sec

This is the number of seconds between when the sym_node table's heartbeat_time column is updated by the heartbeat job. [ Default: 900 ]

start.watchdog.job

Whether the watchdog job is enabled for this node. The watchdog job monitors child nodes to detect if they are offline. Refer to Section 5.10.15, “IOfflineServerListener” for more information. [ Default: true ]

job.watchdog.period.time.ms

This is how often the watchdog job will be run if enabled. [ Default: 3600000 ]

schema.version

This is hook to give the user a mechanism to indicate the schema version that is being synchronized. This property is only valid if you use the default IRuntimeConfiguration implementation. [ Default: ? ]

B.2. Runtime Parameters

Runtime parameters are read periodically from properties files or the database. The following properties are used:

auto.registration

If this is true, registration is opened automatically for nodes requesting it. [ Default: false ]

auto.reload

If this is true, a reload is automatically sent to nodes when they register. [ Default: false ]

auto.reload.reverse

If this is true, a reload is automatically sent from a node after they register. [ Default: false ]

auto.update.node.values.from.properties

Update the node row in the database from the local properties during a heartbeat operation. [ Default: true ]

http.concurrent.workers.max

This is the number of HTTP concurrent push/pull requests symmetric will accept. This is controlled by the NodeConcurrencyFilter. The maximum number of database connections in the database pool should be set to twice this number.[ Default: 20 ]

offline.node.detection.period.minutes

This is the minimum number of minutes that a child node has been offline before taking action. Refer to Section 5.10.15, “IOfflineServerListener” for more information. [ Default: 120 ]

outgoing.batches.peek.ahead.window.after.max.size

This is the maximum number of events that will be peeked at to look for additional transaction rows after the max batch size is reached. The more concurrency in your db and the longer the transaction takes the bigger this value might have to be. [ Default: 100 ]

incoming.batches.skip.duplicates

Whether or not to skip duplicate batches that are received. A duplicate batch is identified by the batch ID already existing in the incoming batch table. If this happens, it means an acknowledgement was lost due to failure or there is a bug. Accepting a duplicate batch in this case can mean overwriting data with old data. Another cause of duplicates is when the batch sequence number is reset, which might happen in a lab environment. Skipping a duplicate batch in this case would prevent data changes from loading. Generally, in a production environment, this setting should be true. [ Default: true ]

num.of.ack.retries

This is the number of times we will attempt to send an ACK back to the remote node when pulling and loading data. [ Default: 5 ]

time.between.ack.retries.ms

This is the amount of time to wait between trying to send an ACK back to the remote node when pulling and loading data. [ Default: 5000 ]

dataextractor.enabled

Enable or disable all data extraction at a node for all channels other than the config channel. [ Default: true ]

dataloader.enabled

Enable or disable all data loading at a node for all channels other than the config channel. [ Default: true ]

cluster.server.id

Set this if you want to give your server a unique name to be used to identify which server did what action. Typically useful when running in a clustered environment. This is currently used by the ClusterService when locking for a node. [ Default:  ]

cluster.lock.timeout.ms

Time limit of lock before it is considered abandoned and can be broken. [ Default: 1800000 ]

cluster.lock.enabled

[ Default: false ]

initial.load.delete.first

Set this if tables should be purged prior to an initial load. [ Default: false ]

initial.load.delete.first.sql

This is the SQL statement that will be used for purging a table during an initial load, provided initial.load.delete.first is set to true. [ Default: delete from %s ]

initial.load.create.first

Set this if tables (and their indexes) should be created prior to an initial load. [ Default: false ]

http.timeout.ms

Sets both the connection and read timeout on the internal HttpUrlConnection. [ Default: 600000s ]

http.compression

Whether or not to use compression over HTTP connections. Currently, this setting only affects the push connection of the source node. Compression on a pull is enabled using a filter in the web.xml for the PullServlet. [ Default: true ]

web.compression.disabled

Disable compression from occurring on Servlet communication. This property only affects the outbound HTTP traffic streamed by the PullServlet and PushServlet. [ Default: false ]

compression.level

Set the compression level this node will use when compressing synchronization payloads. Valid values include: NO_COMPRESSION = 0, BEST_SPEED = 1, BEST_COMPRESSION = 9, DEFAULT_COMPRESSION = -1 [ Default: -1 ]

compression.strategy

Set the compression strategy this node will use when compressing synchronization payloads. Valid values include: FILTERED = 1, HUFFMAN_ONLY = 2, DEFAULT_STRATEGY = 0 [ Default: 0 ]

stream.to.file.enabled

Save data to the file system before transporting it to the client or loading it to the database if the number of bytes is past a certain threshold. This allows for better compression and better use of database and network resources. Statistics in the batch tables will be more accurate if this is set to true because each timed operation is independent of the others. [ Default: true ]

stream.to.file.threshold.bytes

If stream.to.file.enabled is true, then the threshold number of bytes at which a file will be written is controlled by this property. Note that for a synchronization the entire payload of the synchronization will be buffered in memory up to this number (at which point it will be written and continue to stream to disk) [ Default: 32767 ]

job.random.max.start.time.ms

When starting jobs, symmetric attempts to randomize the start time to spread out load. This is the maximum wait period before starting a job. [ Default: 10000 ]

purge.retention.minutes

This is the retention for how long synchronization data will be kept in the SymmetricDS synchronization tables. Note that data will be purged only if the purge job is enabled. [ Default: 7200 ]