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

The WEB-INF/web.xml file is configured with a SymmetricEngineContextLoaderListener, the required SymmetricFilter mapping, and the required SymmetricServlet mapping.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
        http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
    version="2.5">

    <display-name>sync</display-name>
    
    <context-param>
        <param-name>contextConfigLocation</param-name>
        <!-- You can optionally specify other Spring files to 
                load into same context here -->
        <param-value>classpath:symmetric.xml</param-value>
    </context-param>
    
    <filter>
        <filter-name>SymmetricFilter</filter-name>
        <filter-class>
            org.jumpmind.symmetric.web.SymmetricFilter
        </filter-class>
    </filter>
    
    <filter-mapping>
        <filter-name>SymmetricFilter</filter-name>
        <servlet-name>/*</servlet-name>
    </filter-mapping>
    
    <listener>
        <listener-class>
            org.jumpmind.symmetric.SymmetricEngineContextLoaderListener
        </listener-class>
    </listener>
    
    <servlet>
        <servlet-name>SymmetricServlet</servlet-name>
        <servlet-class>
            org.jumpmind.symmetric.web.SymmetricServlet
        </servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    
    <servlet-mapping>
        <servlet-name>SymmetricServlet</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>

</web-app>

This example starts all the SymmetricDS Servlets with Filters to compress the stream, authenticate nodes, and reject nodes when the server is too busy.

The web.base.servlet.path property in symmetric.properties can be set if the SymmetricServlet needs to coexist with other Servlets.

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 root.properties --port 8080 --server

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

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(
                                   "classpath://my-application.properties");

        // this will create the database, sync triggers, start jobs running
        node.start(8080);
        
        // this will stop the node
        node.stop();
    }   

}

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

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

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" />

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 javax.net.ssl.trustStore 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.

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

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
                #
                ip.filters=10.10.4.32/27, 10.5.0.0/16
            

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.

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
                #
                ip.filters=10.10.*.40
            

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
                #
                ip.filters=10.10.40-20.200-1
            

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).

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=10.10.4.32/27, 100.50-40.10-5.*, 35.58.124.89