Search

Configuring the Server

Version 24.2.9064

Configuring the Server

CData Sync includes an embedded Eclipse Jetty web server so that you can run Sync without any external server configuration. The embedded Jetty server requires that JDK 11 or later is installed on the machine.

Windows

In Windows, CData Sync is installed as a service by default. To access the application, you must first ensure that the service is running. Once the service is running, you can access the CData Sync admin console by opening a web browser and entering http://localhost:8181/ in the URL field.

You can also run the application without the service through a java command. CData recommends using the service, but this method can be useful for certain configurations.

Starting and Stopping the Service

You can start and stop the service in either of the following ways:

Start Menu Shortcuts

The CData Sync installer creates start menu shortcuts that allow you to easily use the application. To access these shortcuts, open the Start menu and expand the CData Sync 2023 folder. These shortcuts are available:

  • Start CData Sync: Starts the CData Sync service. By default, this service runs when Windows starts. So, you do not need to run this command every time you run the application.

  • Stop CData Sync: Stops the CData Sync service. This action is necessary when you upgrade Sync.

  • Launch CData Sync Admin Console: Opens a web browser window in your default web browser to the admin console URL, http://localhost:8181/. If the service is not running, the web browser returns an error.

Services Management Console

To open the Services Management Console, open the start menu and type services. Select the Services application that appears.

Scroll down to the service called CData Sync. If that service is running, the Status column says Running. You can right-click the service to access options to start (Start), stop (Stop), and restart (Restart) it.

Command Prompt

Advanced users can use Windows command prompt to issue commands manually to the service. Open a command prompt and change the directory to the installation folder (by default, C:\Program Files\CData\CData Sync).

Note: You can also use a Microsoft PowerShell window to issue these commands, but the syntax is slightly different. Modify the commands accordingly if you use PowerShell.

To start the CData Sync service, issue this command:

sync.exe -start

You can restart or stop the service with these commands:

sync.exe --restart --ServiceName "CData Sync"
sync.exe --stop --ServiceName "CData Sync"

Launching Without the Service

To run CData Sync without starting the service, open a command prompt in the installation folder. Issue the following command to start the application:

java -jar sync.jar

Linux

After you install CData Sync to a location of your choice, you can run CData Sync as a service or run the application manually. CData recommends using a service if you use Sync for critical applications.

Running Sync as a Service

Running CData Sync as a service enables the application to run independently from any user process and to restart automatically upon rebooting. This method is preferred for critical applications.

CData recommends creating a daemon to manage the CData Sync application on Linux. A script that is included in the installation package can do this automatically. You can also create the daemon manually if necessary.

The safest way to configure the CData Sync daemon is to run the script that is included in the installation package, provided that the system uses the systemd daemon manager:

bash ./service

This script creates a daemon called cdata-sync.service. You can then use systemctl to manage the daemon:

systemctl enable cdata-sync
systemctl start cdata-sync

Running the Standalone Application

To start CData Sync without creating a service, use the terminal to open the sync.jar file in the installation directory with a configuration file argument, as shown here:

java -jar sync.jar

Configuring the Embedded Jetty Server

CData Sync comes pre-configured to work immediately in any environment. However, you can customize the way you access the data that is exposed in Sync by generating the sync.properties file in the Sync installation directory (for Windows, this is C:\Program Files\CData\CData Sync by default).

Generating the sync.properties File

Before you can make any customizations to the embedded Jetty server, you must create the sync.properties file. To do so, submit the following command in the installation directory (InstallationDirectory) where the sync.jar file is located:

java -jar sync.jar -GenerateProperties

Note: Once you generate the sync.properties file, any upgrades you make Sync do not overwrite it.

The sync.properties file contains parameters that you can modify to change the port or to enable TLS/SSL, as explained in the following sections.

Changing the Port

To configure the port on which the embedded server listens:

  1. Locate the sync.properties file in InstallationDirectory and open it in a text editor.

  2. Locate the following line where the port is set:

    cdata.http.port=8181

  3. Change this value to the port number that you want.

Changing the Inactivity Timeout

By default, the inactivity (session) timeout for Sync is 10 minutes (600 seconds).

To change the timeout value, set the cdata.session.timeout property in the sync.properties file, as shown below:

cdata.session.timeout=1200

Enabling SSL/TLS

To enable SSL/TLS connections (HTTPS), you also need to modify the sync.properties file in InstallationDirectory, as follows:

  1. Set the cdata.tls.keyStoreType setting to the type of keystore that will be used. Valid values include jks, pkcs12, and jceks.

  2. Set the cdata.tls.keyStorePath setting to the path of the keystore that will be used. Note that ${cdata.home} might be used to refer to InstallationDirectory.

  3. Set the cdata.tls.keyStorePassword setting to the password for the keystore.

  4. Set the cdata.tls.port setting to the port that should be used to host the server.

  5. (Optional) Set the cdata.http.port setting to an empty string to disable plaintext connections.

The final result should look similar to this example:

;; HTTP
cdata.http.port=

;; TLS
cdata.tls.port=8443
cdata.tls.keyStoreType=PKCS12
cdata.tls.keyStorePath=${cdata.home}/mycertificate.pfx
cdata.tls.keyStorePassword=MyPassword

Note: If you obtain an external private key for configuration in Sync, be sure to change the owner of the certificate to the service account that is used to host Sync (cdatasync:cdatasync).

Enabling LDAP Authentication

Sync supports the use of LDAP authentication. To enable LDAP authentication, a user must be defined in Sync where that user matches an LDAP user. For instructions about creating users in Sync, see Adding a User.

To enable LDAP authentication, modify the sync.properties file in InstallationDirectory, as follows:

  1. Set ldap.hostname to the domain name or IP address of the LDAP server.

  2. Set ldap.port to the port on which the LDAP server is running.

  3. Set ldap.authenticatedMethod to the authentication mechanism that should be used when you connect to the LDAP server. Options are none and simple.

  4. Set ldap.bindDn and ldap.bindPassword to the distinguished name and password of a user against which to authenticate the LDAP server.

  5. Set ldap.debug as to whether you want to add debugging information to the server logs. Options are true or false.

  6. Set ldap.user* to the properties that are used to search for user entries.

  7. Set ldap.role* to the properties that are used to search for role entries.

The final result should look similar to this example:

;; LDAP 
cdata.loginService.ldap.enabled=true 
cdata.loginService.ldap.hostname="Server" 
cdata.loginService.ldap.bindDn="CN=CommonName,CN=CommonUsers,DC=ka,DC=com" 
cdata.loginService.ldap.bindPassword="Password" 
cdata.loginService.ldap.debug=true 
cdata.loginService.ldap.port="Port" 
cdata.loginService.ldap.authenticationMethod="AuthMechanism" 
cdata.loginService.ldap.userBaseDn="DC=DomainComponent,DC=DomainComponent" 
cdata.loginService.ldap.userObjectClass="organizationalPerson" 
cdata.loginService.ldap.userRdnAttribute="cn" 
cdata.loginService.ldap.userIdAttribute="sAMAccountName" 
cdata.loginService.ldap.userPasswordAttribute="userPassword" 
cdata.loginService.ldap.forceBindingLogin="true" 
cdata.loginService.ldap.roleBaseDn="DC=ka,DC=com" 
cdata.loginService.ldap.roleNameAttribute="cn" 
cdata.loginService.ldap.roleMemberAttribute="member" 
cdata.loginService.ldap.roleObjectClass="group" 
cdata.loginService.ldap.useLdaps="false"

Deploying CData Sync to Microsoft Internet Information Services (IIS)

Although Sync comes packaged with the embedded Jetty web server, you can also deploy it to the Microsoft IIS web server. The sections that follow provide the steps you need to accomplish a deployment to IIS.

If you have any questions about the steps presented in this section, contact CData Support for assistance.

Prerequisite Steps

Perform the following prerequisite steps before you begin to create a new website:

  1. Download the HttpPlatformHandler modeule from the Microsoft IIS download page.

  2. Create a new folder for Sync (for example, C:\inetpub\sync).

  3. Create the web.config file in the folder that you created in step 2. Then, add the following content to web.config:

    <?xml version="1.0" encoding="UTF-8"?>
 <configuration>
   <system.webServer>
     <handlers>
       <add name="httpplatformhandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified"/>
     </handlers>
     <httpPlatform processPath="C:\Program Files\CData\CData Sync\jre\jdk-17.0.5+8\bin\java.exe" 
                   arguments="-Dcdata.http.port=%HTTP_PLATFORM_PORT% -jar &quot;C:\Program Files\CData\CData Sync\sync.jar&quot;" 
                   stdoutLogEnabled="true" 
                   stdoutLogFile="C:\inetpub\sync\log.txt"
                   >
     </httpPlatform>
   </system.webServer>
 </configuration>

Now you are ready to create a new website on which to host your Sync application, as explained in the next section.

Create a New Website

Note: This example uses the default website.

To host Sync on your website:

  1. Open the IIS Manager.

  2. Right-click Sites (in the Connections pane) and select Add Website.

  3. Enter the following information in the Add Website dialog that is displayed:

    • Site name - The name for your website (for example, “My Sync Website”).

    • Physical path - The physical path of the folder that you created earlier.

    • Type - The protocol type (leave this field as the default value, http).

    • Port - The port number to which you want the website to bind. The default port (80) is fine, or you can choose another port.

  4. Click OK to start the new website.

  5. In your browser, navigate to http://127.0.0.1:YourPortNumber to access Sync.

    Note: You cannot use “localhost” in the HTTP path. You must use the IP value instead.

Configure Directory Permissions

The application must have full access to the Sync application directory for full functionality.

The application directory contains the following folders:

  • connections

  • data

  • db

  • downloads

  • locks

  • logs

  • profiles

To set permissions, locate the application directory for your Sync installation and follow these steps:

  1. Right-click the folder and click Properties. On the Security tab, select Edit > Add.

  2. Enter the following text in the Enter the object names to select box. Substitute the name of your application pool for YourApplicationPool in the line below (example: IIS AppPool\\DefaultAppPool):

    IIS AppPool\\[YourApplicationPool]

  3. Ensure that the application pool has the following permissions:

    • Read

    • Write

    • Modify

    • Read & Execute

    • List Folder Contents

Note: You can also use the command line to allow access to the application pool, as shown in this example:

icacls "www" /grant "IIS APPPOOL\\DefaultAppPool":(OI)(M)

Prevent Application Processes from Unloading

IIS can close a web application for several reasons, including when an idle timeout is exceeded or when IIS deems that the application pool’s resource use is too high. This action might halt background tasks from occurring in your application. Ensure that the application stays running by modifying the following settings:

  1. Enable the optional Application Initialization feature.

    In Windows Server 2012 R2 and Windows Server 2016, open Server Manager and select Dashboard > Quick Start > Add Roles and Features to open the Add Roles and Features wizards. In the Server Roles step, select Web Server (IIS) > Web Server > Application Development > Application Initialization.

    In Windows 8 and Windows 10, open the Control Panel and select Programs and Features > Turn Windows Features On or Off. Then, select Internet Information Services > World Wide Web Services > Application Development Features > Application Initialization.

  2. On the Connections panel in IIS Manager, select Application Pools > YourApplicationPool > Advanced Settings. Then configure these settings:

    • Under the General settings, set Start Mode to AlwaysRunning.

    • Under the Process Model settings, set the Idle Timeout property to 0.

      If you use IIS 8, ensure that the Start Automatically property in the General settings is set to True.

    • Under the CPU section, set the LimitInterval property to 0.

    • Under the Recycling section, set the Regular Time Interval property to 0.

    • Under the Recycling section of the Generate Recycle Event Log Entry node, set Regular Time Interval to False.

Configure ASP.NET App Pool Recycling

IIS recycles regularly so that it can clean up the ASP.NET app pool processes. You can schedule recycling during off-peak hours instead by navigating to the Recycling section and setting Specific Time to True. Then, enter the time (in the format hh:mm:ss) that you want recycling to start.

Preloading Applications

The IIS preloading feature improves performance by allowing the application to run before a user connects. To enable this feature, right-click the web application associated with Sync in the Connections pane and select Manage Application > Advanced Settings. In the PreloadEnabled menu, select True.

When PreloadEnabled is set to True, IIS simulates a user request to the default page of the website or virtual directory so that the application initializes.

Confirm Settings

To open the application and confirm your settings, navigate to http://127.0.0.1/YourPortNumber.

Host TLS/SSL Connections (IIS)

You can use SSL/TLS to protect the confidentiality of your business-critical and mission-critical communications with trading partners. The following steps assume that you already have a certificate that you can use to enable SSL/TLS on your server.

  1. In IIS Manager, click your website’s node from the Connections pane.

  2. Click Bindings in the Actions pane.

  3. Click Add and select HTTPS.

  4. Choose the server certificate.

If you want to require TLS/SSL, double-click the SSL Settings icon in the workspace while your website’s node is still selected. Select Require SSL and click Apply in the Actions pane.

Configuring the Application Directory

The Sync ApplicationDirectory folder contains all the data that is used by the application: configuration data, application data, logging data, certificates, and so on. The default location of ApplicationDirectory depends on whether Sync is hosted via the embedded web server or via an external Java servlet container.

For the embedded web server, ApplicationDirectory is the same as InstallationDirectory. By default, that location is the following:

/opt/sync

When Sync is hosted in an external Java servlet container, ApplicationDirectory is relative to the home directory of the user who is running the server:

~/sync

In this path, ‘~’ resolves to the home directory of the user who is running the server that hosts the application.

You can configure the ApplicationDirectory folder, which is useful in a variety of scenarios:

  • clustering multiple instances of Sync

  • using a shared network drive for application data

  • embedding Sync within other systems that access the same folders

Changing ApplicationDirectory moves the application’s data files. However, it does not move other application resources like EXE files, JAR files, and so on. These resources are held in the InstallationDirectory folder, which might be the same as ApplicationDirectory, but the location of those resources does not change if ApplicationDirectory is changed.

When you use Sync with the embedded Jetty server, ApplicationDirectory is configured in the sync.properties file that is found in InstallationDirectory. Within this server configuration file, you must set the `cdata.app.directory’ setting to the path of the desired directory. The following example demonstrates what this might look like when you set the data directory to a shared folder on a mounted drive:

cdata.app.directory=/mnt/shared/sync

If Sync can locate the cdata.app.directory path and it has the appropriate permissions to read and write at that path, it creates the data folder within the specified directory.

Configure the Application Database

The Sync application database stores several tables of application data, including the following:

  • Jobs

  • Tasks

  • Connections

  • History (both Jobs and Tasks)

  • Application Log (application-level errors and events)

  • Audit Log (user-made changes to the Sync configuration)

By default, Sync uses a Derby database that resides in ApplicationDirectory as the application database. However, you can configure the application to use an enterprise database like SQL Server, PostgreSQL, or MySQL.

Embedded Java Server

When you use Sync with the embedded Jetty server, the application database is configured in the sync.properties file that resides in InstallationDirectory. Within this server configuration file, you must set the cdata.app.db setting to a Java Database Connectivity (JDBC) connection string that contains the appropriate connection parameters for the database that you want. The following examples illustrate this setting for the MySQl, PostgreSQL, and SQl databases:

MySQL

cdata.app.db=jdbc:cdata:mysqlserver=localhost;port=3306;database=mysql;user=MyUserName;password=MyPassword

PostgreSQL

cdata.app.db=jdbc:cdata:postgresql:server=localhost;port=5432;database=postgresql;user=MyUserName;password=MyPassword

SQL Server

cdata.app.db=jdbc:cdata:sql:server=localhost;database=sqlserver;user=MyUserName;password=MyPassword

If Sync can establish a connection successfully with the cdata.app.db connection string, it uses that database as the application database.

Login Lockouts

Sync automatically locks out users who enter incorrect passwords too many times in order to prevent brute-force attacks. By default, a user who enters six incorrect passwords within five minutes is locked out for thirty minutes.

You can modify the lockout settings by editing the XML configuration file that governs the web-server behavior. These three settings are relevant to lockouts:

  • LockoutFailedAttempts - the number of incorrect passwords that trigger a lockout. Set LockoutFailedAttempts to 0 to disable lockouts.

  • LockoutMinutes - the duration of the lockout. The default duration is thirty minutes.

  • LockoutTimeCheckPeriod - the period after which the number of failed attempts is reset to 0. The default period is five minutes.

For the embedded Jetty server, you can modify lockout settings in the sync.properties file by adding a comma-separated list of name:value pairs to initParameters, as shown below:

cdata.initParameters=LockoutFailedAttempts:0

Common Issues and Solutions

This section lists common issues that you can encounter when you deploy Sync in a Java environment. The recommended solution for each issue is included. For additional help, contact CData Technical Support at [email protected].

Issue

Sync fails to start, or it starts by using an AppDirectory other than what is expected

This error might indicate that Sync does not have the permissions that are required to access ApplicationDirectory.(ApplicationDirectory is a folder that stores critical information regarding the configuration of jobs, connections, transformations, and so on.) One possible cause for this error is running Sync as a local user before you set it up as a service. In this case, it is possible that certain resources created by the application were created under the local user. As a result, those resources are not available when you run Sync as a service.

In a Linux operating environment, the easiest way to ensure that the service account (or any other account that you want to use to run Sync) can access ApplicationDirectory is to use the chown command. For example, if ApplicationDirectory is in the default Linux location and Sync should run under the service account, the following command should resolve the error:

sudo chown -R cdatasync:cdatasync /opt/sync