> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sync.cdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuring the Server

export const companyNameLower = "cdata";

export const companyName = "CData";

export const siteNameShortLower = "sync";

export const siteNameShort = "Sync";

export const siteName = "CData Sync";

<Note>This page has content that is only applicable to {siteNameShort} Self-Hosted deployments.</Note>

{siteName} includes an embedded Eclipse Jetty web server so that you can run {siteNameShort} without any external server configuration. The embedded Jetty server requires Java Development Kit (JDK) 17 or later to be installed on the machine.

## Windows

In Windows, {siteName} 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 {siteName} admin console by opening a web browser and entering [http://localhost:8181/](http://localhost:8181/) in the URL field.

You can also run the application without the service through a `java` command. {companyName} 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](#start-menu-shortcuts) (recommended)
* The [Services Management Console](#services-management-console)
* [Command prompt](#command-prompt) commands

#### Start Menu Shortcuts

The {siteName} installer creates start menu shortcuts that allow you to easily use the application. To access these shortcuts, open the **Start** menu and select from these available options:

* **Start {siteName}**: Starts the {siteName} 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 {siteName}**: Stops the {siteName} service. This action is necessary when you [upgrade {siteNameShort}](../software-upgrades).

#### 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 **{siteName}**. 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.</Note>

To start the {siteName} service, issue this command:

```sh theme={null}
sync.exe -start
```

You can restart or stop the service with these commands:

```sh theme={null}
sync.exe --restart --ServiceName "CData Sync"
sync.exe --stop --ServiceName "CData Sync"
```

### Launching Without the Service

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

```sh theme={null}
java -jar sync.jar
```

## Linux

After you [install {siteName} to a location of your choice](./installation-configuration#linux), you can run {siteName} as a service or run the application manually. {companyName} recommends using a service if you use {siteNameShort} for critical applications.

### Running {siteNameShort} as a Service

Running {siteName} as a service enables the application to run independently from any user process and to restart automatically upon rebooting.

Follow these steps to ensure that your Linux installation of {siteNameShort} functions as expected as a service:

1. When you install {siteNameShort}, ensure that the user who is performing the installation has read and write permissions for the installation directory. The root user works fine for this.
2. Run the **service.sh** script. This script is located at the root of the extracted setup archive. For example, if you extract the archive to `/opt/sync`, the script is located in `/opt/sync/service.sh`.
3. After you run **service.sh**, enable and start the service according to the service manager that is used by your Linux distribution:
   1. Enable the service by submitting this command:

      `systemctl enable cdatasync`

   2. Enable your service manager:

      For **init.d,** submit this command:

      `sudo service cdatasync start`

      For **systemd,** submit this command:

      `sudo systemctl start cdatasync`

<Note>Regardless of how you choose to deploy {siteNameShort}, the files and folders within *`ApplicationDirectory`* must be readable and writable by the user who is running the application. The service installer that is included with the Java edition setup uses **cdatasync** as this user.</Note>

If the application was previously run under a different user account and you need to restore the required permissions for the **cdatasync** user to run the application, submit the following command (modify the directory path if necessary):

`sudo chown -R cdatasync:cdatasync /opt/sync`

### Running the Standalone Application

To start {siteName} 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:

```sh theme={null}
java -jar sync.jar
```

## Configuring the Embedded Jetty Server

{siteName} comes pre-configured to work immediately in any environment. However, you can customize the way you access the data that is exposed in {siteNameShort} by generating the sync.properties file in the {siteNameShort} 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 {siteNameShortLower}.jar file is located:

```
java -jar sync.jar -GenerateProperties
```

<Note>Once you generate the `sync.properties` file, any upgrades you make to {siteNameShort} do not overwrite it.</Note>

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.

<Note>You can store sensitive values in the `sync.properties` file in encrypted form instead of plaintext. For more information, see [Encrypting Sensitive Configuration Values](#encrypting-sensitive-configuration-values).</Note>

### 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 {siteNameShort} 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. For improved security, you can store this value in encrypted form in sync.properties.
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><span>If you obtain an external private key for configuration in {siteNameShort}, be sure to change the owner of the certificate to the service account that is used to host {siteNameShort} (<code style={{padding: "0"}}>cdata{siteNameShortLower}:cdata{siteNameShortLower}</code>).</span></Note>

### Enabling LDAP Authentication

{siteNameShort} supports the use of LDAP authentication. To enable LDAP authentication, a user must be defined in {siteNameShort} where that user matches an LDAP user. For instructions about creating users in {siteNameShort}, see [Adding a User](../administration/settings-page/user-management/user-management#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. For improved security, you can store the password value in encrypted form in sync.properties.
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"
```

## Configuring the Application Directory

The {siteNameShort} *`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 {siteNameShort} 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:

```bash theme={null}
/opt/sync
```

When {siteNameShort} 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 {siteNameShort}
* using a shared network drive for application data
* embedding {siteNameShort} 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 {siteNameShort} 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:

```bash theme={null}
cdata.app.directory=/mnt/shared/sync
```

If {siteNameShort} 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

Starting with version 26.2, {siteNameShort} uses an embedded H2 database that resides in *`ApplicationDirectory`* as the default application database.

Existing installations continue to use the legacy embedded Derby database. {siteNameShort} does not automatically migrate existing installations to H2.

The {siteNameShort} 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 {siteNameShort} configuration)

The application database resides in *`ApplicationDirectory`* when you use an embedded database.

You can also configure {siteNameShort} to use an enterprise database, such as Microsoft SQL Server, PostgreSQL, or MySQL, as explained in the next section. While there are alternative ways to configure an external database (for example, as explained in [AWS-AMI Edition](./aws-ami-edition#application-database) or [Azure Marketplace Edition](./azure-marketplace-edition#application-database)), the recommended approach is to follow the steps in the [Migration documentation](../administration/settings-page/migration).

### Embedded Java Server

When you use {siteNameShort} 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:mysql:server=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 {siteNameShort} can establish a connection successfully with the `cdata.app.db` connection string, it uses that database as the application database.

## Encrypting Sensitive Configuration Values

{siteName} supports storing sensitive configuration values in encrypted form in the sync.properties file. Encrypting sensitive configuration values allows you to protect credentials in sync.properties while preserving normal configuration behavior.

The embedded web server automatically decrypts encrypted values when it reads configuration settings. No additional steps are required after you replace a plaintext value with its encrypted equivalent.

You can use encrypted values for the following configuration properties:

* Application database connection: `cdata.app.db`
* TLS keystore password: `cdata.tls.keyStorePassword`
* LDAP login service settings: `cdata.loginService.ldap.*`

Each of these properties accepts either a plaintext value or an encrypted value. When an encrypted value is provided, {siteNameShort} decrypts it at run time before {siteNameShort} uses the value.

You can generate encrypted values from the command line by using the `-EncryptConnectionString` parameter. This parameter accepts any string, not only connection strings.

**Example:**

```sh theme={null}
java -jar sync.jar -EncryptConnectionString "YourSensitiveValue"
```

This example outputs the encrypted value to the console. The last line of the output contains the encrypted string.

**Output:**

```
Encrypting value...
Encryption successful.
SECURE:AbCdEfGhIjKlMnOpQrStUvWxYz1234567890==
```

Copy the encrypted value and replace the corresponding plaintext value in the sync.properties file.

When {siteNameShort} reads configuration values from sync.properties, it checks for the `SECURE:` or `ENCRYPTEDA:` prefix. If a prefix is present, {siteNameShort} decrypts the value before it is used internally.

Encrypted values are preserved during configuration processing and serialization. This behavior ensures that sensitive settings remain encrypted when configuration data is written and reloaded.

## Login Lockouts

{siteNameShort} 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:

```bash theme={null}
cdata.initParameters=LockoutFailedAttempts:0
```

## Common Issues and Solutions

This section lists common issues that you can encounter when you deploy {siteNameShort} in a Java environment. The recommended solution for each issue is included. For additional help, contact {companyName} Technical Support at **{siteNameShortLower}support@{companyNameLower}.com**.

**Issue**

**{siteNameShort} fails to start, or it starts by using an AppDirectory other than what is expected**

This error might indicate that {siteNameShort} 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 {siteNameShort} 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 {siteNameShort} as a service.

**Recommended Solution**

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 {siteNameShort}) can access *`ApplicationDirectory`* is to use the `chown` command. For example, if *`ApplicationDirectory`* is in the default Linux location and {siteNameShort} should run under the service account, the following command should resolve the error:

```bash theme={null}
sudo chown -R cdatasync:cdatasync /opt/sync
```