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-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
Startup parameters are read once from properties files and apply only during start up. The following properties are used:
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: ]
The class name of the JDBC driver. If
db.jndi.name
is set, this property is ignored. [ Default: com.mysql.jdbc.Driver ]
The JDBC URL used to connect to the database. If
db.jndi.name
is set, this property is ignored.
[ Default: jdbc:mysql://localhost/symmetric ]
The database username, which is used to login, create, and update SymmetricDS tables.
To use an encrypted username, see Section 5.5, “Encrypted Passwords”.
If
db.jndi.name
is set, this property is ignored. [ Default: symmetric ]
The password for the database user.
To use an encrypted password, see Section 5.5, “Encrypted Passwords”.
If
db.jndi.name
is set, this property is ignored. [ Default: ]
The initial size of the connection pool. If
db.jndi.name
is set, this property is ignored. [ Default: 5 ]
The maximum number of connections that will be allocated in the pool. If
db.jndi.name
is set, this property is ignored. [ Default: 10 ]
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 ]
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 ]
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.
The timeout in seconds for queries running on the database. [ Default: 300 ]
This is how long the default transaction time is. This needs to be fairly big to account for large data loads. [ Default: 7200 ]
This is the default fetch size for streaming result sets into memory from the database. [ Default: 1000 ]
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: ]
Indicates that case should be ignored when looking up references to tables using the metadata api. [ Default: true ]
If this is true, the configuration and runtime tables used by SymmetricDS are automatically created during startup. [ Default: true ]
If this is true, when symmetric starts up it will try to upgrade tables to latest version. [ Default: true ]
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 ]
If this is true, a Symmetric client node to accept self signed certificates. [ Default: true ]
If specified, a Symmetric client node will use basic authentication when communicating with its server node using the given user name. [ Default: ]
If specified, the password used for basic authentication. [ Default: ]
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: ]
If specified, the password for basic authentication for an embedded server or standalone server node. [ Default: ]
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: ]
When symmetric tables are created and accessed, this is the prefix to use for the table name. [ Default: sym ]
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 ]
Whether the push job is enabled for this node. [ 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 sync triggers job is enabled for this node. [ Default: true ]
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 ]
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 ]
This is how often the purge job will be run. [ Default: 600000 ]
This is how often accumulated statistics will be flushed out to the database from memory. [ Default: 600000 ]
The base servlet path for when embedding SymmetricDS with in another web application. [ Default: ]
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 ]
Update the node row in the database from the local properties during a heartbeat operation. [ Default: true ]
This is the download rate for the HTTP symmetric transport. A value of -1 means full throttle. [ Default: -1 ]
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 ]
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 ]
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 ]
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 ]
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 amount of time to wait between trying to send an ACK back to the remote node when pulling and loading data. [ Default: 5000 ]
Enable or disable all data extraction at a node for all channels other than the config channel. [ Default: true ]
Enable or disable all data loading at a node for all channels other than the config channel. [ Default: true ]
If an insert is received, but the row already exists, then try an update instead. [ Default: true ]
If an update is received, but it affects no rows, then try to insert instead. [ Default: true ]
If a delete is received, but it affects no rows, then continue. [ Default: true ]
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: ]
Time limit of lock before it is considered abandoned and can be broken. [ Default: 1800000 ]
[ Default: false ]
Set this if tables should be purged prior to an initial load. [ Default: false ]
Set this if tables (and their indexes) should be created prior to an initial load. [ Default: false ]
Sets both the connection and read timeout on the internal HttpUrlConnection. [ Default: 600000s ]
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 ]
Disable compression from occurring on Servlet communication. This property only affects the outbound HTTP traffic streamed by the PullServlet and PushServlet. [ Default: false ]
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 ]
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 ]
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 ]
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 ]
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 ]
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 ]
This is how often the route job will be run. [ Default: 10000 ]
This is how often the push job will be run. [ Default: 60000 ]
This is how often the pull job will be run. [ Default: 60000 ]
If scheduled, the sync triggers job will run nightly. This is how long after midnight that job will run. [ Default: 15 ]
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: ? ]
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: ]
The URL where this node can be contacting for synchronization. [ Default: http://localhost:8080/sync ]
The node group id for this node. [ Default: default ]
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: ]
Specify the transport type. Supported values currently include: http, internal. [ Default: http ]
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 ]