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.
Location | Required | Description |
---|---|---|
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 | N | Changes 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
Startup parameters are read once from properties files and apply only during start up. The following properties are used:
If this is true, when symmetric starts up it will try to create the necessary tables. [ Default: true ]
Provide the path to a SQL script that can be run to do initial setup of a registration server. This script will only be run on a registration server if the node_identity cannot be found. [ Default: ]
Capture and send SymmetricDS configuration changes to client nodes. [ Default: true ]
Update the node row in the database from the local properties during a heartbeat operation. [ Default: true ]
This is the amount of time table meta data will be cached before re-reading it from the database [ Default: 3600000 ]
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: ]
These are settings that will be passed to the JDBC driver as connection properties. Suggested settings by database are as follows: Oracle db.connection.properties=oracle.net.CONNECT_TIMEOUT=300000;oracle.net.READ_TIMEOUT=300000;SetBigStringTryClob=true [ Default: ]
Determines whether delimited identifiers are used or normal SQL92 identifiers (which may only contain alphanumerical characters and the underscore, must start with a letter and cannot be a reserved keyword). [ Default: true ]
Specify your database driver [ Default: org.h2.Driver ]
Specify a SQL statement that will be run when a database connection is created [ Default: ]
This is the default number of rows that will be sent to the database as a batch when SymmetricDS uses the JDBC batch API. Currently, only routing uses JDBC batch. The data loader does not. [ Default: 100 ]
This is the default fetch size for streaming result sets. [ Default: 100 ]
Name of a JNDI data source to use instead of using SymmetricDS's connection pool. When this is set the db.url is ignored. Using a JNDI data source is relevant when deploying to an application server. [ Default: ]
Indicates that case should be ignored when looking up references to tables using the database's metadata api. [ Default: true ]
Name of class that can extract native JDBC objects and interact directly with the driver. Spring uses this to perform operations specific to database, like handling LOBs on Oracle. [ Default: org.springframework.jdbc.support.nativejdbc.CommonsDbcpNativeJdbcExtractor ]
Specify your database password [ Default: ]
The initial size of the connection pool [ Default: 5 ]
The maximum number of connections that will be allocated in the pool The http.concurrent.workers.max value should be half or less than half of this value. [ Default: 40 ]
The maximum number of connections that can remain idle in the pool, without extra ones being released [ Default: 20 ]
This is how long a request for a connection from the datasource will wait before giving up. [ Default: 30000 ]
This is how long a connection can be idle before it will be evicted. [ Default: 120000 ]
The minimum number of connections that can remain idle in the pool, without extra ones being created [ Default: 5 ]
If set to true forces database columns that contain character data to be read as bytes (bypassing JDBC driver character encoding) so the raw values be encoded using the system default character set (usually UTF8). This property was added to bypass MySQL character encoding so the raw data can be converted to utf8 directly. [ Default: false ]
Most symmetric queries have a timeout associated with them. This is the default. [ Default: 300 ]
Specify your database URL [ Default: jdbc:h2:mem:setme;AUTO_SERVER=TRUE ]
Specify your database user [ Default: please set me ]
This is the query to validate the database connection in Connection Pool. It is database specific. The following are example statements for different databases. MySQL db.validation.query=select 1 Oracle db.validation.query=select 1 from dual DB2 db.validation.query=select max(1) from syscat.datatypes [ Default: ]
Use to map the version string a zseries jdbc driver returns to the 'zseries' dialect [ Default: DSN08015 ]
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. Please do not use underscores in this name. [ Default: SymmetricDS ]
The external id for this SymmetricDS node. The external id is usually used as all or part of the node id. [ Default: please set me ]
Enables File Synchronization capabilities [ Default: true ]
How long file sync should wait in millis for the exclusive lock used by file tracker or the shared lock used by file sync push/pull jobs. [ Default: 300000 ]
The node group id that this node belongs to [ Default: please set me ]
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 ]
This is the amount of time the host will keep a concurrent connection reservation after it has been attained by a client node while waiting for the subsequent reconnect to push. [ Default: 20000 ]
During SSL handshaking, if the URL's hostname and the server's identification hostname mismatch, the verification mechanism will check this comma separated list of server names to see if the cert should be accepted (see javax.net.ssl.HostnameVerifier.) Set this value equal to 'all' if all server names should be accepted. Set this value to blank if a valid SSL cert is required. [ Default: ]
Specify the type of line feed to use in JMX console methods. Possible values are: text or html. [ Default: text ]
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 ]
Whether or not files are local to client only, so we must send the file to MySQL to load. If client is running on same server as MySQL, then this can be set to false to have MySQL read file directly. [ Default: true ]
Maximum number of bytes to write to file before running with 'LOAD DATA INFILE' to MySQL [ Default: 1000000000 ]
Maximum number of rows to write to file before running with 'LOAD DATA INFILE' to MySQL [ Default: 100000 ]
This is the precision that is used in the number template for oracle triggers [ Default: 30,10 ]
Requires access to gv$transaction. This is the threshold by which clock can be off in an oracle rac environment. It is only applicable when oracle.use.transaction.view is set to true. [ Default: 60000 ]
Requires access to gv$transaction [ Default: false ]
This is the URL this node will use to register and pull it's configuration. If this is the root server, then this may remain blank and the configuration should be inserted directly into the database [ Default: please set me ]
The class name for the Security Service to use for encrypting and decrypting database passwords [ Default: org.jumpmind.security.SecurityService ]
The name of the active log file. This is used by the system to locate the log file for analysis and trouble shooting. It is set to the default log file location for the standalone server. If deployed as a war file, you should update the value. Note that this property does not change the actual location the log file will be written. It just tells SymmetricDS where to find the log file. [ Default: ../logs/symmetric.log ]
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_host table for the current node. [ Default: true ]
Whether the background initial load extractor job is started. [ Default: true ]
Whether the pull job is enabled for this node. [ Default: true ]
Whether the purge job is enabled for this node. [ Default: true ]
Whether the push job is enabled for this node. [ Default: true ]
Whether the refresh cache job is enabled for this node. [ Default: false ]
Whether the routing job is enabled for this node. [ Default: true ]
Whether the stage management job is enabled for this node. [ Default: true ]
Whether the statistic flush job is enabled for this node. [ Default: true ]
Whether the sync triggers job is enabled for this node. [ Default: true ]
Whether the watchdog job is enabled for this node. [ Default: true ]
When symmetric tables are created and accessed, this is the prefix to use for the tables. [ Default: sym ]
The url that can be used to access this SymmetricDS node. The default setting of http://$(hostName):31415/sync should be valid of the standalone launcher is used with the default settings The tokens of $(hostName) and $(ipAddress) are supported for this property. [ Default: http://$(hostName):31415/sync/$(engineName) ]
Specify the transport type. Supported values currently include: http, internal. [ Default: http ]
Indicate whether the batch servlet (which allows specific batches to be requested) is enabled. [ Default: true ]
Runtime parameters are read periodically from properties files or the database. The following properties are used:
If this is true, registration is opened automatically for nodes requesting it. [ Default: false ]
If this is true, a reload is automatically sent to nodes when they register [ Default: false ]
If this is true, a reload is automatically sent from a source node to all target nodes after the source node has registered. [ Default: false ]
Whether triggers should fire when changes sync into the node that this property is configured for. [ Default: true ]
If this is true, when symmetric starts up it will make sure the triggers in the database are up to date. [ Default: true ]
If this is true, when a configuration change is detected, symmetric will make sure all triggers in the database are up to date. [ Default: true ]
If this is true, then run the sync triggers process at startup [ Default: true ]
This parameter can be used to indicate that bean shell load filters will handle missing tables. Useful for the case where you want to make, for example, global catalog or schema changes at the destination in the case where the catalog, schema, or table doesn't exist but the BSH will handle it. [ Default: false ]
This is the amount of time channel entries will be cached before re-reading them from the database. [ Default: 60000 ]
This is the amount of time conflict setting entries will be cached before re-reading them from the database. [ Default: 600000 ]
This is the amount of time grouplet entries will be cached before re-reading them from the database. [ Default: 600000 ]
This is the amount of time load filter entries will be cached before re-reading them from the database. [ Default: 600000 ]
This is the amount of time node group links entries will be cached before re-reading them from the database. [ Default: 600000 ]
This is the amount of time node security entries will be cached before re-reading them from the database. [ Default: 0 ]
This is the amount of time transform entries will be cached before re-reading them from the database. [ Default: 600000 ]
This is the amount of time trigger entries will be cached before re-reading them from the database. [ Default: 600000 ]
Enables clustering of jobs. [ Default: false ]
Indicate that this node is being run on a farm or cluster of servers and it needs to use the database to 'lock' out other activity when actions are taken. [ Default: 1800000 ]
Set the compression level this node will use when compressing synchronization payloads. @see java.util.zip.Deflater NO_COMPRESSION = 0 BEST_SPEED = 1 BEST_COMPRESSION = 9 DEFAULT_COMPRESSION = -1 [ Default: -1 ]
Set the compression strategy this node will use when compressing synchronization payloads. @see java.util.zip.Deflater FILTERED = 1 HUFFMAN_ONLY = 2 DEFAULT_STRATEGY = 0 [ Default: 0 ]
This is the expected increment value for the data_id in the data table. This is useful if you use auto_increment_increment and auto_increment_offset in MySQL. Note that these settings require innodb_autoinc_lock_mode=0, otherwise the increment and offset are not guaranteed. [ Default: 1 ]
Disable the extraction of all channels with the exception of the config channel [ Default: true ]
Disable the loading of all channel with the exception of the config channel. This property can be set to allow all changes to be extracted without introducing other changes in order to allow maintenance operations. [ Default: true ]
Indicates that the current value of the row should be recorded in the incoming_error table [ Default: false ]
Tables that are missing at the target database will be ignored. This should be set to true if you expect that in some clients a table might not exist. If set to false, the batch will fail. [ Default: false ]
This is the maximum number of rows that will be supported in a single transaction. If the database transaction row count reaches a size that is greater than this number then the transaction will be auto committed. The default value of -1 indicates that there is no size limit. [ Default: 10000 ]
Amount of time to sleep before continuing data load after dataloader.max.rows.before.commit rows have been loaded. This is useful to give other application threads a chance to do work before continuing to load. [ Default: 5 ]
Indicate whether the process of inserting data, data_events and outgoing_batches for a reload is transactional. The only reason this might be marked as false is to reduce possible contention while multiple nodes connect for reloads at the same time. [ Default: true ]
This is a setting that instructs the data capture and data load to treat JDBC TIME, DATE, and TIMESTAMP columns as if they were VARCHAR columns. This means that the columns will be captured and loaded in the form that the database stores them. Setting this to true on MySQL will allow datetime columns with the value of '0000-00-00 00:00:00' to be synchronized. [ Default: false ]
null [ Default: false ]
null [ Default: 7200000 ]
null [ Default: 0 ]
null [ Default: 1 ]
null [ Default: 7200000 ]
null [ Default: 0 ]
null [ Default: 1 ]
Specify whether to push node_host records to configured push clients. If this is true the node for this instance and the node_host rows for all children instances will be pushed to all nodes that this node is configured to push to. [ Default: true ]
This is the number of seconds between when the sym_node_host table's heartbeat_time column is updated. This property depends on the frequency of the heartbeat job. If the heartbeat job is set to run every 10 minutes and this property is set to 10 seconds, then the heartbeat will only update every 10 minutes. [ Default: 0 ]
When this property is set to true the heartbeat process will run at server startup. Prior to 3.4 the heartbeat always happened at startup. [ Default: false ]
When this is set to true, SymmetricDS will update fields in the sym_node table that indicate the number of outstanding errors and/or batches it has pending [ Default: false ]
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. @see web.compression.disabled to enable/disable the filter [ Default: true ]
This is the number of HTTP concurrent push/pull requests SymmetricDS will accept. This is controlled by the NodeConcurrencyFilter. The number is per servlet the filter is applied to. The db.pool.max.active value should be twice this value. [ Default: 20 ]
The HTTP client connection, during a push, buffers the entire outgoing pay-load locally before sending it. Set this to true if you are getting heap space errors during a push. Note that basic auth may not work when this is turned on. [ Default: false ]
When HTTP chunking is turned on, this is the size to use for each chunk. [ Default: 30720 ]
Sets both the connection and read timeout on the internal HttpUrlConnection [ Default: 7200000 ]
Indicates whether batches that have loaded successfully should be recorded in the incoming_batch table. Note that if this is set to false, then duplicate batches will NOT be skipped because SymmetricDS will have no way of knowing that a batch has already loaded. This parameter can be set to false to reduce contention on sym_incoming_batch for systems with many clients. [ Default: true ]
This instructs symmetric to attempt to skip duplicate batches that are received. Symmetric might be more efficient when recovering from error conditions if this is set to true, but you run the risk of missing data if the batch ids get reset (on one node, but not another) somehow (which is unlikely in production, but fairly likely in lab or development setups). [ Default: true ]
This is SQL that will run on the client after an initial load finishes. [ Default: ]
This is SQL that will run on the client before an initial load starts. [ Default: ]
Indicates that the SQL used to extract data from a table for an initial load should concatenate the data using the same SQL expression that a trigger uses versus concatenating the data in code. [ Default: false ]
Set this if tables should be created prior to an initial load. [ Default: false ]
Set this if tables should be purged prior to an initial load. [ Default: false ]
This is the SQL statement that will be used for purging a table during an initial load. [ Default: delete from %s ]
The number of threads available for concurrent extracts of initial load batches. [ Default: 20 ]
The number of milliseconds to wait until the lock will be broken on an initial load extract job. [ Default: 7200000 ]
Indicate that if both the initial load and the reverse initial load are requested, then the reverse initial load should take place first. [ Default: true ]
Indicate that the extract job job should be used to extract reload batches [ Default: false ]
Indicate that the initial load events should be put on the reload channel. If this is set to false each table will be put on it's assigned channel during the reload. [ Default: true ]
null [ Default: 60000 ]
null [ Default: 60000 ]
null [ Default: 0 0/5 * * * * ]
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: 900000 ]
This is how often the initial load extract queue job will run in the background [ Default: 10000 ]
This is how often the pull job will be run to schedule pulls of nodes. [ Default: 60000 ]
This is how often the data gaps purge job will be run. [ Default: 0 0 0 * * * ]
This is how often the incoming batch purge job will be run. [ Default: 0 0 0 * * * ]
This is the number of batches that will be purged in one database transaction. [ Default: 5000 ]
This is the number of batches that will be purged from the data_event table in one database transaction. [ Default: 5 ]
This is the number of data ids that will be purged in one database transaction. [ Default: 5000 ]
This is how often the outgoing batch and data purge job will be run. [ Default: 0 0 0 * * * ]
This is how often the push job will be run to schedule pushes to nodes. [ Default: 60000 ]
This is when the refresh cache job will run. [ Default: 0/30 * * * * * ]
This is how often the router will run in the background [ Default: 10000 ]
This is when the stage management job will run. [ Default: 15000 ]
This is how often accumulated statistics will be flushed out to the database from memory. [ Default: 0 0/5 * * * * ]
This is when the sync triggers job will run. [ Default: 0 0 0 * * * ]
null [ Default: 3600000 ]
If jobs need to be synchronized so that only one job can run at a time, set this parameter to true [ Default: false ]
The amount of time a thread can hold a shared or exclusive lock before another thread can break the lock. The timeout is a safeguard in case an unexpected exception causes a lock to be abandoned. Restarting the service will clear all locks. [ Default: 1800000 ]
While waiting for a lock to be released, how often should we check the lock status in the sym_lock table in the database. [ Default: 10000 ]
Automatically update data, data_event and outgoing_batch tables to allow only row level locking. [ Default: true ]
Whether or not triggers should be allowed to fire when bulk loading data. [ Default: false ]
Maximum number of rows to write to file before running with "BULK INSERT" to SQL-Server [ Default: 100000 ]
Specify a UNC network path to the tmp\bulkloaddir directory for SQL Server to access bulk load files. Use this property with bulk loader when SymmetricDS is on a separate server from SQL Server. [ Default: ]
Use ntext for the data capture columns and cast to nvarchar(max) in the trigger text so that nvarchar, ntext and nchar double byte data isn't lost when the database collation for char types isn't compatible with n char types. [ Default: false ]
Whether or not to replace rows that already exist, based on primary key or unique key. If set to false, duplicates will be skipped. [ Default: true ]
This is a bean shell script that will be used to generate the node id for a registering node [ Default: ]
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 ]
This is the number of minutes that a node has been offline before taking action A value of -1 (or any negative value) disables the feature. [ Default: -1 ]
The maximum number of unprocessed outgoing batch rows for a node that will be read into memory for the next data extraction. [ Default: 50000 ]
This is the number of data events that will be batched and committed together while building a batch. Note that this only kicks in if the prospective batch size is bigger than the configured max batch size. [ Default: 10 ]
The number of milliseconds parameters will be cached by the ParameterService before they are reread from the file system and database. [ Default: 600000 ]
The amount of time a single pull worker node_communication lock will timeout after. [ Default: 7200000 ]
This is the minimum time that is allowed between pulls of a specific node. [ Default: 0 ]
The number of threads created that will be used to pull nodes concurrently on one server in the cluster. [ Default: 1 ]
This is the retention time for how long a extract request will be retained [ Default: 7200 ]
This is the retention for how long log summary messages will be retained in memory. [ Default: 60 ]
This is the retention time for how long a registration request will be retained [ Default: 7200 ]
This is the retention for how long synchronization data will be kept in the symmetric synchronization tables. Note that data will be purged only if the purge job is enabled. [ Default: 1440 ]
This is the retention for how long statistic data will be kept in the symmetric stats tables. Note that data will be purged only if the statistics flush job is enabled. [ Default: 1440 ]
The amount of time a single push worker node_communication lock will timeout after. [ Default: 7200000 ]
This is the minimum time that is allowed between pushes to a specific node. [ Default: 0 ]
The number of threads created that will be used to push to nodes concurrently on one server in the cluster. [ Default: 1 ]
This is the number of times registration will be attempted before being aborted. The default value is -1 which means an endless number of attempts. This parameter is specific to the node that is trying to register, not the node that is providing registration. [ Default: -1 ]
Indicates whether SymmetricDS should be re-initialized immediately before registration. [ Default: false ]
Enables the REST API [ Default: false ]
Enables the REST API to update the heartbeat when pulling data [ Default: false ]
Use the order by clause to order sym_data when selecting data for routing. Most databases order the data naturally and might even have better performance when the order by clause is left off. [ Default: true ]
Select data to route from sym_data using a simple > start_gap_id query if the number of gaps in sym_data_gap are greater than the following number [ Default: 100 ]
null [ Default: 1440 ]
When true, delete the gaps instead of marking them as OK or SK. [ Default: true ]
null [ Default: 50000 ]
This is the maximum number of data that will be routed during one run. It should be a number that well exceeds the number rows that will be in a transaction. [ Default: 50000000 ]
Enable to collect routing statistics for each batch and log the statistics when a batch goes into error. [ Default: false ]
This is the number of gaps that will be included in the SQL that is used to select data from sym_data. If there are more gaps than this number, then the last gap will in the SQL will use the end id of the last gap. [ Default: 100 ]
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: 2000 ]
This is the time that any gaps in data_ids will be considered stale and skipped. [ Default: 7200000 ]
null [ Default: 330 ]
This is hook to give the user a mechanism to indicate the schema version that is being synchronized. [ Default: ? ]
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 ]
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 ]
If stream.to.file.enabled is true, then this is how long a file will be retained in the staging directory after it has been marked as done. [ Default: 3600000 ]
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 ]
This is the number of maximum number of bytes to synchronize in one connect. [ Default: 1048576 ]
Disable this property to prevent table triggers from being created before initial load has completed. [ Default: true ]
Enable this property to force a compare of old and new data in triggers. If old=new, then don't record the change in the data capture table. This is currently supported by the following dialects: mysql, oracle, db2, postgres, sql server [ Default: false ]
Disable compression from occurring on Servlet communication. This property only affects the outbound HTTP traffic streamed by the PullServlet and PushServlet. [ Default: false ]
Server configuration is read from conf/symmetric-server.conf
for settings needed by the server
before the parameter system has been initialized.
Enable synchronization over HTTP. [ Default: true ]
Port number for synchronization over HTTP. [ Default: 31415 ]
Use a trust manager that allows self-signed server SSL certificates. [ Default: true ]
Enable synchronization over HTTPS (HTTP over SSL). [ Default: false ]
Port number for synchronization over HTTPS (HTTP over SSL). [ Default: 31417 ]
List host names that are allowed for server SSL certificates. [ Default: all ]
Enable Java Management Extensions (JMX) web console. [ Default: true ]
Port number for Java Management Extensions (JMX) web console. [ Default: 31416 ]