Java Edition


Java Edition


The Java edition includes an embedded Jetty web server so that Sync can be run without any external server configuration. In addition, the installation includes a .WAR file that can be deployed to any Java servlet container like Tomcat, Jetty, JBoss, WebLogic, or WebSphere.

The embedded Jetty server requires that JDK 1.8 or later is installed on the machine. Deploying to an external Java servlet requires Servlet 3.0 (Jetty 8+, Tomcat 7+, JBoss EAP 6/7, Glassfish 3, WebLogic 12+, WebSphere 8+, etc).

Using the Embedded Jetty Server

To start the embedded Jetty server, simply run the sync.jar file located in the Sync installation directory. This directory also contains a service script, which may be used to set up a systemd or init.d service on unix systems.

By default, the embedded server hosts Sync on port 8181 and only accepts plaintext connections (HTTP and not HTTPS).

After starting the server, access the web UI by directing a browser to http://localhost:8181. The application will prompt for creating the username/password credentials for the first user of the application (which will have the role of ‘admin’).

Changing the Port

To configure the port that the embedded server listens on, find the sync.xml file in the installation directory and open it in a text editor. Find the definition of the HTTP connector as indicated by this XML:

<New id="httpConnector" class="org.eclipse.jetty.server.ServerConnector">

Within this definition, modify the following line to change the configured port:

<Set name="port">8181</Set>

Enabling SSL/TLS

Enabling SSL/TLS connections (HTTPS) also involves modifying the sync.xml file in the installation directory. Find the definition of the HTTP connector:

<New id="httpConnector" class="org.eclipse.jetty.server.ServerConnector">

Within this definition (as a direct child of the above New element), supply an sslContextFactory argument by adding the following XML block:

<Arg name="sslContextFactory">
  <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
    <Set name="KeyStorePath"><SystemProperty name="sync.home" default"." />/keystore</Set>
    <Set name="KeyStorePassword">mypassword</Set>
  </New>
</Arg>

Note: The Arg element shown above must be adjacent to other Arg elements at the beginning of the connector definition. This block must not be placed after the Set element that defines the server port, for example.

The KeyStorePath element defines the location of the SSL/TLS certificate used when hosting the SSL/TLS server. The above example assumes that a ‘keystore’ folder has been created in the Sync installation directory and this folder contains a PFX certificate called ‘mycert’. The KeyStorePassword element should be set to the password that corresponds to the configured certificate.

Starting and Stopping the Server

If the service script has been used to set up a CData Sync service, please reference the Running as a Service section below. Otherwise, the Running In-Process section is applicable.

Running In-Process

The embedded Jetty server is started by executing the sync.jar file extracted from the application download during setup. Standard Java syntax can be used to execute this file and start the server:

java -jar sync.jar

To stop the server, simply pass an additional parameter to this command:

java -jar sync.jar -stop

Running as a Service

The Sync service can be manipulated using standard system service commands, referencing ‘sync’ as the name of the service.

To start the service:

systemctl start sync

To stop the service:

systemctl stop sync

To restart the service:

systemctl restart sync

Configuration in Tomcat

Deploy the WAR File

You have several options for deploying a WAR file to Tomcat.

  • Copy the WAR file into the webapps folder.
  • Deploy the WAR file from within the management console in Tomcat. The Tomcat documentation covers this method in more detail.

It is possible that the WAR file may exceed the default maximum size allowed for file uploads in Tomcat. To overcome errors during deployment, you can edit the WEB.XML file of the manager application to allow larger files. Depending on your tomcat configuration, this file may be located in ‘/usr/share/tomcat7-admin/manager/WEB-INF’, or in another similar directory. In this file, you can change the size in bits of the maximum allowed file size. For example, to allow deployment of a 200MB WAR file, edit the following values to change the maximum allowed file size:

<multipart-config>
	<!-- 200MB max -->
	<max-file-size>209715200</max-file-size>
	<max-request-size>209715200</max-request-size>
	<file-size-threshold>0</file-size-threshold>
</multipart-config>

JAAS Configuration

In order for Sync to dynamically manage users within the application, JAAS must be configured as described in the following subsections.

Login Module

Create a JAAS configuration file with the name jaas.config located here: $CATALINA_BASE/conf/jaas.config

The content for this file should be as follows:

Sync {
    sync.LoginModule required debug=true;
};

JAASRealm Module

Create the context for sync by adding the sync.xml file located here: $CATALINA_BASE/conf/Catalina/localhost/sync.xml

Within the Context block, add a Realm element as follows:

<Context>
	<Realm className="org.apache.catalina.realm.JAASRealm" appName="Sync"
    userClassNames="sync.SimplePrincipal"
    roleClassNames="sync.GroupPrincipal" />
</Context>

Update the Host element in server.xml by setting the copyXML attribute to true. For example:

<Host name="localhost"  appBase="webapps" unpackWARs="true" autoDeploy="true" copyXML="true">

Make the Login Module Visible

The JVM must be pointed towards the Login Module (jaas.config) in order for the configuration to be visible. Set an environmental variable within $CATALINA_BASE/bin/catalina.bat as follows:

set "JAVA_OPTS=%JAVA_OPTS% -Djava.security.auth.login.config=%CATALINA_BASE%\\conf\\jaas.config"

Configure Data Directory Permissions

Allow the user of the process running the Java servlet container read/write access to the data directory:

  • Windows: C:\\ProgramData\\CData\\sync\\
  • Unix or Mac OS X: ~/cdata/sync/

Restart your Tomcat server for the changes to take effect. You can now log in to the application.

Configuration in JBoss

Note that JBoss AS is not supported.

Deploy the WAR File

There are several ways that you can deploy a WAR file to JBoss:

  • You can copy the WAR file into the JBOSS_HOME/standalone/deployments subfolder.
  • You can also use the JBoss Administration Console to install the WAR file.

JAAS Configuration

In order for Sync to dynamically manage users within the application, JAAS must be configured as described in the following subsections.

Login Module

Edit the standalone.xml configuration file (located here: standalone/configuration/standalone.xml) with a login module as follows:

<subsystem xmlns="urn:jboss:domain:security:2.0">
  <security-domain name="SyncRealm" cache-type="default">
      <authentication>
          <login-module code="sync.LoginModule" flag="required">
              <module-option name="isJBoss" value="true"/>
          </login-module>
      </authentication>
  </security-domain>
</subsystem>

JBoss Web File

Create a jboss-web.xml file in the WEB-INF folder of the deployment. Set the contents of the file to the following:

<jboss-web>
    <security-domain>java:/jaas/SyncRealm</security-domain>
</jboss-web>

Configure Data Directory Permissions

Allow the user of the process running the Java servlet container read/write access to the data directory:

  • Windows: C:\\ProgramData\\CData\\sync\\
  • Unix or Mac OS X: ~/cdata/sync/

Restart the server and log into the application.

Configuration in WebSphere

Configure Data Directory Permissions

Allow the user of the process running the Java servlet container read/write access to the data directory:

  • Windows: C:\\ProgramData\\CData\\sync\\
  • Unix or Mac OS X: ~/cdata/sync/

Restart the server and log into the application.

Configure the WebSphere Class Loader

In order for WebSphere to load the application resources correctly, the following steps are required:

  1. Within WebSphere, navigate to: Application -> Application Types -> WebSphere enterprise applications
  2. Select Sync
  3. Select ‘Class loading and update detection’
  4. Choose ‘Classes loaded with local class loader first (parent last)’
  5. Choose ‘Single class loader for application’
  6. Select OK -> Save

JAAS Configuration

The following process is required to allow Sync to dynamically manage users in WebSphere Application Server:

  • Deploy CData Sync
  • Enable application security
    • Security → Global security → Enable application security
  • Add custom login module to System Login
    • Security → Global security → Java Authentication and Authorization Service → System logins → WEB_INBOUND → New → sync.LoginModule
    • Check the “Use login module proxy”
    • Select OPTIONAL under Authentication strategy
    • Add isWebSphere under Custom properties, set it to true
    • The sync.LoginModule must be prior to the com.ibm.ws.security.server.lm.ltpaLoginModule.
  • Create groups
    • Users and Groups → Manage Groups → Create
    • Create sync_admin_, sync_standard, sync_operator groups
  • Map groups to roles
    • Applications → Application Types → WebSphere enterprise applications → <sync_war\> Security role to user/group mapping
    • Map sync_admin group to sync_admin role
    • Map sync_standard group to sync_standard role
    • Map sync_support group to sync_operator role
    • Map “All Authenticated in Application’s Realm” to sync_user_ role
  • Restart WebSphere

Configuration in WebLogic

Deploy the WAR File

To use the deployment wizard in WebLogic to deploy the WAR file:

  1. Click Deployments
  2. In the Deployments table, click Install.
  3. Enter the path to the WAR file and then select the WAR file from the list.
  4. Select Install this deployment as an application.
  5. Select Custom Roles: Use roles that are defined in the Administration Console; use policies that are defined in the deployment descriptor. Selecting this option allows you to manage the roles and users in WebLogic’s administration console, while WebLogic loads the roles and policies defined in the application.

Configure Data Directory Permissions

Allow the user of the process running the Java servlet container read/write access to the data directory:

  • Windows: C:\\ProgramData\\CData\\sync\\
  • Unix or Mac OS X: ~/cdata/sync/

Restart the server and log into the application.

Configuration in Jetty

While CData Sync comes with an embedded Jetty web server, the application can also be used with an external Jetty setup.

Deploy the WAR File

Copy the WAR file into Jetty’s webapps folder.

Configure the Login Service for the Java Realm

You must also configure a login service for the application with the name CDataSyncRealm. Below is a HashLoginService example:

<Call name="addBean">
  <Arg>
    <New class="org.eclipse.jetty.security.HashLoginService">
      <Set name="name">CDataSyncRealm</Set>
      <Set name="config"><Property name="jetty.home" default="."/>/etc/realm.properties</Set>
    </New>
  </Arg>
</Call>

Configure JAAS

The following steps are required to configure JAAS and allow Sync to manage application users.

Add JAAS Module

Run the following command to install the JAAS module:

java -jar {JETTY_HOME}/start.jar --add-to-start=jaas

Create Login Module

Create a login configuration file with the name login.config located here: etc/login.conf

The content for this file should be as follows:

Sync {
    sync.LoginModule required debug=true;
};

Update the Security Handler

The Security Handler configuration can be found in the sync.xml configuration file. Modify the securityHandler block as follows:

<Set name="securityHandler">
  <New class="org.eclipse.jetty.security.ConstraintSecurityHandler">
   <Set name="loginService">
     <New class="org.eclipse.jetty.jaas.JAASLoginService">
       <!-- This name is the same as **login-config -> realm-name** in web.xml  -->
       <Set name="name">SyncRealm</Set>
       <!-- The LoginModuleName must match the name of your LoginModule as declared in your login module configuration file -->
       <Set name="loginModuleName">Sync</Set>
       <!-- Set custom role principal class name -->
       <Set name="roleClassNames">
           <Array type="java.lang.String">
             <Item>sync.GroupPrincipal</Item>
           </Array>
         </Set>
     </New>
   </Set>
  </New>
</Set>

Configure Data Directory Permissions

Allow the user of the process running the Java servlet container read/write access to the data directory:

  • Windows: C:\\ProgramData\\CData\\sync\\
  • Unix or Mac OS X: ~/cdata/sync/

Restart the server and log into the application.

User Management

Upon first starting, Sync will prompt for the creation of a user with username/password credentials. After this first user is created, users can be added, deleted, and managed via the Settings page of the application, under the Users tab.

When deploying Sync to an external Java servlet (i.e. when not using the embedded server included with the application), JAAS configuration is required to allow Sync to manage users. The sections above detail the process of JAAS configuration for each specific external servlet.

Find and Configure the Application Directory

Sync’s Application Directory holds all of the data used by the application: configuration data, application data, logging data, certificates, etc. The default location of the Application Directory depends on whether Sync is hosted via the embedded web server or an external Java servlet container.

For the embedded web server, the Application Directory is the same as the installation directory, which by default is the following:

/opt/cdata/sync

When hosting Sync in an external Java servlet container, the Application Directory is relative to the home directory of the user running the server:

~/cdata/sync (where ‘~’ resolves to the home directory of the user running the server hosting the application)

The Application Directory can be configured to be a different folder. Changing the Application Directory will move the application’s data files but will not move other application resources like .exe’s, .jar’s, etc. These resources are held in the Installation Directory, which may be the same as the Application Directory but will not change if the Application Directory is changed.

Embedded Java Server

When using the Java edition with the embedded Jetty server, the application database is configured in the sync.xml file found in the Installation Directory. Within this server configuration file, the AppDirectory environment variable must be set to the path to the desired directory. The following example demonstrates what this might look like when setting the data directory to a shared folder on a mounted drive:

<Call name="setInitParameter">
  <Arg>AppDirectory</Arg>
  <Arg>/mnt/shared/sync</Arg>
</Call>

If Sync can find the path, and has the appropriate permissions to read and write at the given path, it will create the data folder within the specified directory.

External Java Server

When using the Java edition with an external Java servlet (any server other than the Jetty server that is included with the application), the details of configuring the application data directory depend upon the specific servlet used. Using the syntax appropriate for the specific servlet, the AppDirectory environment variable must be set to the path to the desired directory.

If Sync can find the AppDirectory path, and has the appropriate permissions to read and write at the given path, it will create the data folder within the specified directory.

Configure the Application Database

Sync’s Application Database stores several tables of application data, including:

  • Jobs
  • Tasks
  • Connections
  • History (both Jobs and Tasks)
  • Application Settings
  • Application Log (application-level errors and events)
  • Audit Log (user-made changes to Sync’s configuration)

By default, Sync uses a Derby database located in the Application Directory as the Application Database, but this can be configured to use an enterprise database like SQL Server, PostgreSQL, or MySQL.

Embedded Java Server

When using the Java edition with the embedded Jetty server, the application database is configured in the sync.xml file found in the installation directory. Within this server configuration file, the APP_DB environment variable must be set to a JDBC connection string containing the appropriate connection parameters for the desired database. For example:

<Call name="setInitParameter">
  <Arg>APP_DB</Arg>
  <Arg>jdbc:mysql:Server=MySQLServer;Port=3306;Database=mysql;User=user;Password=password</Arg>
</Call>

If Sync can successfully establish a connection with the APP_DB connection string, it will use that database as the application database.

External Java Server

When using the Java edition with an external Java servlet (any server other than the Jetty server that is included with the application), the details of configuring the application database depend upon the specific servlet used. Using the syntax appropriate for the specific servlet, one of the following approaches should be used when configuring the server:

  • Define a JNDI datasource to include the connection properties for the target database.
  • Set the APP_DB environment variable to a JDBC connection string.

If Sync can use the JDNI datasource or APP_DB connection string to connect to a database, it will use that database as the application database.

Login Lockouts

Sync will automatically lock out users who enter incorrect passwords too many times in order to prevent brute force attacks. By default, a user who enters 6 incorrect passwords within 5 minutes will be locked out for 30 minutes.

These settings can be modified by editing the XML configuration file that governs the web server behavior. There are 3 settings relevant to lockouts:

  • LockoutFailedAttempts - the number of incorrect passwords that will trigger a lockout (set this to 0 to disable lockouts)
  • LockoutMinutes - the duration of the lockout (default 30 minutes)
  • LockoutTimeCheckPeriod - the period after which the number of failed attempts is reset to 0 (default 5 minutes)

Embedded Jetty Server

The syntax for editing these settings within the sync.xml file for the embedded web server is the following:

<Call name="setInitParameter">
  <Arg>LockoutFailedAttempts</Arg>
  <Arg>0</Arg>
 </Call>

Tomcat

The syntax for editing these settings within Tomcat’s server.xml is the following:

<Context>
   <Parameter name="LockoutFailedAttempts" value="0" />
</Context>