Search

.Net Edition

Version 22.0.8483

.Net Edition

The Windows version of the CData Sync comes packaged with a stand-alone embedded web server and can also be hosted in IIS. This section describes various options for hosting the application in Windows.

If you do not have experience with IIS, the embedded server is recommended. The embedded server is automatically deployed at installation and provides a simple interface for server-level administration tasks such as configuring logging, running the application as a service, and enabling SSL/TLS.

Embedded Server

This section shows how to configure the stand-alone, embedded Web server, including how to Host TLS/SSL Connections and configure the Cloud Gateway, a reverse SSH tunnel.

When hosted in the stand-alone server, the application can be run as a Windows service:

  1. Right-click the Sync icon in the taskbar and click Server Options.
  2. Select the Run as a Windows Service option.
  3. Save your changes.

Host TLS/SSL Connections (Embedded Server)

You can require TLS as well as offer services in plaintext. This section shows how to host TLS/SSL connections in the stand-alone server included with the Windows edition of the application. To deploy TLS/SSL for the Java edition, refer to the documentation for the Java servlet you are using to host the application.

  1. Right-click the icon for the application in the Windows system tray and click Server Options.
  2. On the Web Server tab, select Enable TLS and select a port that you want to listen on for TLS connections.
  3. Click the button next to the TLS Server Certificate box to select a private key certificate. The certificate with private key must be installed to the Local Computer certificate store. If there are no certificates available which match that criteria, click Create New Certificate to create a simple certificate for this purpose.

Server Dialog

The server will restart and begin serving TLS requests after you save your changes.

Manage Personal Certificates

If you would like to manage the certificates that are available in the certificate selection dialog, they are located in the Personal certificate store for the local computer. To add a certificate to the Windows store:

  1. Launch Microsoft Management Console by entering mmc from the Run menu.
  2. Click File > Add/Remove Snap-In.

  3. Select Certificates from the Available Snap-Ins table and click Add.

    Add Snap-In

  4. Select Computer Account > Local Computer.
  5. After adding the snap-in, click Certificates (Local Computer) > Personal > Certificates to display the available certificates. The certificates for which a private key is available have a small key icon superimposed over the certificate icon.
  6. To import a certificate from the local disk into this store, click Action > All Tasks > Import. After completing the import wizard, the certificates are available in the application certificate selection dialog.

Cloud Gateway

The Cloud Gateway feature of Sync provides a simple way to expose the application to the Internet without the need for firewall changes. As long as a publicly accessible SSH server is available, Sync may be accessed via a port on the publicly accessible SSH server by leveraging an SSH Reverse Tunnel.

To leverage this functionality, right-click the application icon in the system tray and select Server Options. Navigate to the Cloud Gateway tab, as shown below, and enter the following information:

Cloud Gateway

  • Host indicates the SSH server that Sync connects to.
  • Port indicates the port on which the SSH host is listening for connections. Most SSH servers listen on port 22, which is the default value.
  • Authentication Type indicates the type of authentication to use. Password, Public Key, Multi-Factor, and Keyboard Interactive are supported.
  • User indicates the username Sync uses to authenticate to the SSH server.
  • Password indicates the password used to authenticate, if required, by the Authentication Type used.
  • Certificate indicates the certificate Sync uses to authenticate to the SSH server during Public Key Authentication.
  • Server Fingerprint indicates the SSH host key fingerprint of the SSH server. This value is read-only and purely informational.
  • Forwarding Port indicates the port that the publicly available SSH server listens on for connections to forward to Sync.

In addition, it may be necessary to change the configuration of your SSH Server to allow port forwarding. Default SSH server configuration may not always enable port forwarding to non-localhost addresses. For example, if connecting to an OpenSSH server, the GatewayPorts property must be set to yes or clientspecified in the SSH server configuration file.

After you enter this information, click Test Connection to test the connection to the SSH server to verify the validity of the information provided. If successful, once the application is restarted, Sync is accessible via the Forwarding Port on the SSH host. For example, if the SSH server my.ssh.host was specified, with a Forwarding Port of 8401, entering https://my.ssh.host:8401 in a browser would cause the communication to be forwarded to the local machine where Sync is running, allowing public access despite it not being directly accessible.

Windows Authentication

By default, the embedded web server uses ASP.NET’s forms-based authentication, wherein a username/password combination must be entered into a webform (i.e. a login portal) to grant access to the administration console. Sync also supports Windows/Active Directory authentication to grant application access to specific Windows users or security groups.

To enable Windows authentication, simply open the embedded web server configuration UI (right-click the Sync icon in the system tray and select Server Options) and toggle the Authentication Type field under the ‘Web Server’ tab.

By default, access is granted to the current Windows user managing the web server. To configure the users and groups permitted to access the application, add new users within the Users tab of the Settings page in the application.

Users must be added within the application using DOMAIN\Username syntax. Users must be added individually, as an entire group cannot be granted access to the application at this time.

Configuration in IIS

These instructions cover several versions of IIS and Windows. If you run into difficulties following one of these guides, see the last section, Troubleshooting. If your version is not covered in this tutorial or if you have other questions, contact our support team for further assistance.

IIS 8, 8.5, and 10

Create a New Web Application

Note: This example uses the default website.

To host the application on your website:

  1. In the IIS Manager, expand the node for your server in the Connections panel.
  2. Expand the Sites node, right-click your website, and click Add Application.
  3. In the Add Application dialog that is displayed, enter the following information:
Alias The name for the application; for example, “sync”.
Application Pool The application pool associated with the application. This tutorial uses “DefaultAppPool”.
Physical Path The path to the www directory, in the directory where the application was installed. The default location for this directory is C:\Program Files\CData\CData Sync\www.
Configure Directory Permissions

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

In Sync 2020 and earlier, the data directory and the application install directory were the same—by default, C:\Program Files\CData\CData Sync. If you upgraded from a previous version of Sync to Sync 2021, this is likely still your data directory.

In Sync 2021, the data directory was split from the application install directory. The program executables still install in C:\Program Files\CData\Sync. However, the data files moved to C:\ProgramData\CData\sync\.

The application directory contains the following folders:

  • connections
  • data
  • db
  • downloads
  • locks
  • logs
  • profiles

The install directory contains:

  • Program executables (CData.Sync.exe, CData.Exe) and configuration files
  • the www folder and subfolders

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, click Edit > Add.
  2. In the Enter the object names to select box, enter the following, substituting the name of the application pool: IIS AppPool\\[your-application-pool]. For example, IIS AppPool\\DefaultAppPool.

  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. For example:

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

Prevent Application Processes from Unloading

IIS can shut down a web application for several reasons, including when an idle timeout is exceeded, or when it deems the application pool’s resource use is too high. This may 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 click Dashboard > Quick Start > Add Roles and Features. The Add Roles and Features wizard opens. In the Server Roles step, click Web Server (IIS) > Web Server > Application Development > Application Initialization.

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

  2. In the IIS Manager, click Application Pools in the Connections panel.
  3. In the workspace, right-click the application pool and click Advanced Settings.

  4. In the General settings, set Start Mode to AlwaysRunning.

  5. In the Process Model settings, set the Idle Timeout property to 0.

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

  6. In the CPU section, set the LimitInterval property to 0.
  7. In the Recycling section, set the Regular Time Interval property to 0.
  8. In the Generate Recycle Event Log Entry node, under the Recycling section, 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 instead schedule recycling during off-peak hours by navigating to the Recycling section, and setting Specific Time to True and enter the times to recycle in the format hh:mm:ss.

Preloading Applications

IIS’s preloading feature improves performance by allowing the application to run prior to a user connecting. 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, navigate to http://localhost/sync. If you are getting any errors, see Troubleshooting.

IIS 7 and 7.5

Create a New Web Application

To host the application on your website.

Note: This example uses the default website.

  1. In the IIS Manager, expand the node for your server in the Connections panel.
  2. Expand the Sites node, right-click your website, and click Add Application.
  3. In the Add Application dialog that is displayed, enter the following information:
Alias The name for the application; for example, “sync”.
Application Pool The application pool associated with the application. This tutorial uses “DefaultAppPool”.
Physical Path The path to the www directory, in the directory where the application was installed. The default location for this directory is C:\Program Files\CData\CData Sync\www.
Configure Permission

See Configure Permissions for IIS 8, 8.5, and 10 above. The information is applicable across IIS versions.

Prevent Application Processes from Unloading

IIS can shut down a web application for several reasons, including when an idle timeout is exceeded, or when it deems the application pool’s resource use is too high. This may halt background tasks from occurring.

This version of IIS does not have configuration settings to always keep the Web application running. To ensure that the application pool is always running so that background tasks will occur, you need to configure a script to issue an HTTP request to the application periodically.

In IIS 7.5, you can ensure that the application stays running by modifying the following settings:

  1. Install the Application Initialization Extension for IIS 7.5. You can download it at http://www.iis.net/download/ApplicationInitialization.
  2. In the IIS Manager, click Application Pools in the Connections panel.
  3. In the workspace, right-click the application pool and click Advanced Settings.
  4. In the General settings, ensure that Start Automatically is set to True.
  5. In the Process Model settings, set the Idle Timeout property to 0.
  6. In the CPU section, set the LimitInterval property to 0.
  7. In the Recycling section, set the Regular Time Interval property to 0.
  8. In the Generate Recycle Event Log Entry node, under the Recycling section, set Regular Time Interval to False.
  9. Modify the settings for the application pool entry in the ApplicationHost.config file, located in C:\Windows\System32\inetsrv\config\. Add startMode=”AlwaysRunning” and autoStart=”True” to the appropriate entry. For example:
<applicationPools>
<add name="DefaultAppPool" managedRuntimeVersion="v4.0" startMode="AlwaysRunning" autoStart="true"/>
</applicationPools>
Configuring ASP.NET App Pool Recycling

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

Preloading Applications

IIS’s preloading feature improves performance by allowing the application to run prior to a user connecting. To enable this feature, edit the ApplicationHost.config file (C:\Windows\System32\inetsrv\config\ApplicationHost.config) and add the preloadEnabled attribute to the <application> element associated with the application. The application node is a child element of the sites node, as shown in the following example:

<sites>
  <site name="Default Web Site" id="1">
  <application path="/sync" applicationPool="DefaultAppPool"  preloadEnabled="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, navigate to http://localhost/sync. If you are getting any errors, see Troubleshooting.

Host TLS/SSL Connections (IIS)

SSL/TLS can be used to protect the confidentiality of your business-critical and mission-critical communications with trading partners. The following steps assume you already have a certificate 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 on the Actions pane.
  3. Click Add and select HTTPS.
  4. Choose the server certificate.
  5. If you want to require TLS/SSL, double-click the SSL Settings icon in the workspace with your website’s node still selected. Select Require SSL and click Apply in the Actions pane.

Troubleshooting

The sections below provide resolutions for several common errors.

The application stops responding some time after I log out.

IIS is possibly unloading your application after it times out from inactivity. By default, IIS terminates the worker process assigned to the application after 20 minutes of inactivity. The section “Prevent Application Processes from Unloading”, in the steps to set up your version of IIS, explains how to override this feature.

In IIS 7.5, 8, and 8.5, you can ensure the application stays running by modifying the configuration settings in the IIS Manager.

Versions of IIS before IIS 7.5 do not have configuration settings to always keep the web application running. To ensure that the application pool is always running so that background tasks occur, you need to configure a script to issue an HTTP request to the application periodically.

Visiting http://localhost/application results in a “Page Cannot Be Displayed” error (an HTTP 404 error).

This can happen if ASP.NET is not enabled. To confirm if ASP.NET is enabled, go to http://localhost/sync/favicon.ico. If this page loads successfully, then ASP.NET is not enabled.

If you are running IIS7 or higher, select Control Panel > Programs (or Programs and Features) > Turn Windows Features On or Off > Internet Information Services > World Wide Web Services > Application Development Features. Select the check box next to ASP.NET.

If you are using Windows Server 2003 open the Internet Information Services Manager, expand the local computer node, and click Web Service Extensions > ASP.NET > Allow. You may also need to follow the steps below.

If you are running IIS 6 or earlier open the Windows command prompt, navigate to the .NET Framework version installation, such as C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727, and issue the aspnet_regiis -i</b> command. You may have to change Framework to Framework64 if you are using a 64-bit processor. The output should resemble the following:

C:\\WINDOWS\\Microsoft.NET\\Framework\\v2.0.50727>aspnet\_regiis -i
  Start installing ASP.NET (2.0.50727).
  ...
  Finished installing ASP.NET (2.0.50727).

Restart IIS by issuing the iisreset command. The output should resemble the following:

  C:\\WINDOWS\\Microsoft.NET\\Framework\\v2.0.50727>iisreset

  Attempting stop...
  Internet services successfully stopped
  Attempting start...
  Internet services successfully restarted

The section is locked at a parent level. Locking is either by default (overrideModeDefault=”Deny”), or set explicitly by a location tag with overrideMode=”Deny” or the legacy allowOverride=”false”.

This error can occur if ASP.NET is not installed.

IIS 8 and 8.5

First, determine the version of the ASP.NET CLR that is used by your application pool. You will need to install the version of ASP.NET that ships the same ASP.NET CLR. For example, ASP.NET 4.5 uses CLR version 4.0. You can find the CLR version in the IIS Manager by clicking Application Pools in the Connections panel. The .NET CLR Version property is displayed in the list of application pools.

In Windows Server 2012, open Server Manager and click Dashboard > Quick Start > Add roles and features. The Add Roles and Features wizard opens. Click Web Server (IIS) > Web Server > Application Development and select the appropriate version of ASP.NET.

In Windows 8, open the Control Panel and click Programs and Features > Turn Windows Features On or Off. Click Internet Information Services > World Wide Web Services > Application Development Features > Application Development and select the appropriate version of ASP.NET.

IIS 7 and 7.5

In Windows 7, open the Control Panel and click Programs and Features > Turn Windows Features On or Off. Click Internet Information Services > World Wide Web Services > Application Development Features > ASP.NET.

In Windows Server 2008, open Server Manager and click Add Role Services. Select Web Server > Application Development > ASP.NET.

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.

More information about user management and roles can be found in the User Roles section.

Find and Configure the Application Directory

Sync’s Application Directory holds all of the data used by the application: Job and connection data, application data, logging data, etc. Typically, the Application Directory defaults to the following location:

C:\ProgramData\CData\Sync

The Application Directory can be configured to be a different folder, which is useful in a variety of scenarios:

  • Clustering multiple instances of Sync
  • Using a shared network drive for application data
  • Embed Sync within other systems accessing the same folders.

Changing the Application Directory will move the application’s data files but will not move other application resources like .exe’s, .dll’s, etc.

Web.Config

The Application Directory is configured in the Web.Config file within the ‘www’ folder of the Installation Directory.

This file contains a commented-out AppDirectory block that that describes the following appSettings tag. The path to the desired Application Directory should be set as the ‘AppDirectory’ key with appSettings.

The Application Directory can be set to any local or network path for which the application has read and write permissions.

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 SQLite database in the Application Directory as the Application Database, but this can be configured to use an enterprise database like SQL Server, PostgreSQL, or MySQL.

Web.Config

The Application Database is configured in the Web.Config file within the ‘www’ folder of the Installation Directory.

This file contains a commented-out AppDb block that that describes the following connectionStrings tag. The connection string and provider name for the target database should be set within the ‘AppDb’ key.

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 when the 7th try fails.

These settings can be modified by editing the Web.Config file within the ‘www’ folder of the Installation Directory. 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)

Each of these settings can be set under the appSettings tag in the Web.Config file like the following:

<appSettings>
     <add key="LockoutFailedAttempts" value="0"/>
</appSettings>"