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-ds.jar file. This file has all the default settings along with descriptions.
symmetric.properties N Provided by the end user on the classpath. The first symmetric.properties found on the classpath will be used.
symmetric.properties N Provided by the end user in the current system user's user.home directory.
named properties file 1 N Provided by the end user as a Java system property (i.e. -Dsymmetric.override.properties.file.1=file://my.properties) or in the constructor of a SymmetricEngine .
named properties file 2 N Provided by the end user as a Java system property (i.e. -Dsymmetric.override.properties.file.2=classpath://my.properties) or in the constructor of a SymmetricEngine .
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:

db.jndi.name

The name of the database connection pool to use, which is registered in the JNDI directory tree of the application server. It is recommended that this DataSource is NOT transactional, because SymmetricDS will handle its own transactions. If NOT using a JNDI connection pool, you must provide information about the database connection using the db.driver , db.url , db.user , and db.password properties instead, which will create a pool of connections using the db.pool properties. [ 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.spring.bean.name

The name of a Spring bean to use as the DataSource. If you want to use a different DataSource other than the provided DBCP version that SymmetricDS uses out of the box, you may set this to be the Spring bean name of your DataSource.

db.sql.query.timeout.seconds

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

db.tx.timeout.seconds

This is how long the default transaction time is. This needs to be fairly big to account for large data loads. [ Default: 7200 ]

db.jdbc.streaming.results.fetch.size

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

db.default.schema

This is the schema that will be used for metadata lookup. Some dialect automatically figure this out using database specific SQL to get the current schema. [ Default:  ]

db.metadata.ignore.case

Indicates that case should be ignored when looking up references to tables using the metadata api. [ Default: true ]

auto.config.database

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

auto.upgrade

If this is true, when symmetric starts up it will try to upgrade tables to latest version. [ 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: ]

embedded.webserver.basic.auth.username

If specified, the username for basic authentication for an embedded server or standalone server node. Specifying the username and password is all that's needed to enable basic authentication for an embedded server or standalone server node. [ Default: ]

embedded.webserver.basic.auth.password

If specified, the password for basic authentication for an embedded server or standalone server node. [ 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 ]

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 ]

start.push.job

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

start.pull.job

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

start.purge.job

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

start.synctriggers.job

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

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 ]

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 6.15, “IOfflineServerListener” for more information. [ Default: true ]

job.purge.period.time.ms

This is how often the purge job will be run. [ Default: 600000 ]

job.statflush.period.time.ms

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

web.base.servlet.path

The base servlet path for when embedding SymmetricDS with in another web application. [ 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.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 6.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 environement. Skipping a duplicate batch in this case would prevent data changes from loading. Generally, in a production envionment, 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 ]

dataloader.enable.fallback.update

If an insert is received, but the row already exists, then try an update instead. [ Default: true ]

dataloader.enable.fallback.insert

If an update is received, but it affects no rows, then try to insert instead. [ Default: true ]

dataloader.allow.missing.delete

If a delete is received, but it affects no rows, then continue. [ 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.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 ]

statistic.retention.minutes

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

job.route.period.time.ms

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

job.push.period.time.ms

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

job.pull.period.time.ms

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

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 ]

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: ? ]

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: ]

transport.type

Specify the transport type. Supported values currently include: http, internal. [ Default: http ]

hsqldb.initialize.db

If using the HsqlDbDialect, this property indicates whether Symmetric should setup the embedded database properties or if an external application will be doing so. [ Default: true ]