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

# Deploying CData Sync to External Servlets

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>

The {siteName} installation includes a WAR file that can be deployed to any Java servlet container like Apache Tomcat, Eclipse Jetty, or IBM WebSphere. Deploying to an external Java servlet container requires Servlet 3.0 (Jetty 8+, Tomcat 7+, WebSphere 8+, and so on).

## Configuration in Apache Tomcat

### Deploy the WAR File

You have two 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 Apache Tomcat documentation covers this method in more detail. See the documentation for your version of Tomcat.

It is possible that the WAR file might exceed the default maximum size that is 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 might reside in `/usr/share/tomcat7-admin/manager/WEB-INF` or in another similar directory. In this file, you can change the size, in bytes, of the maximum allowed file size. For example, to allow deployment of a 200-MB WAR file, edit the following values to change the maximum allowed file size:

```xml theme={null}
<multipart-config>
     <!-- 200-MB max -->
  <max-file-size>209715200</max-file-size>
  <max-request-size>209715200</max-request-size>
  <file-size-threshold>0</file-size-threshold>
</multipart-config>
```

### Configure the Java Authentication and Service (JAAS)

To enable {siteNameShort} to manage users dynamically within the application, you must configure the JAAS as described in the following subsections.

#### Create the Login Module

Create a JAAS configuration file with the name jaas.config in this folder: `$CATALINA_BASE/conf/`.

Include the following content in jaas.config to use standard authentication:

```
Sync {
  sync.LoginModule required;
};
```

If you want to use LDAP or Windows Active Directory to authenticate users, add this content instead:

```
Sync {
  com.sun.security.auth.module.LdapLoginModule REQUIRED
    userProvider="ldaps://ab1cdef234.wfsaas.net:636/CN=Users,DC=example,DC=com"
    authIdentity="{USERNAME}@example.com"
    userFilter="(&(|(samAccountName={USERNAME})(userPrincipalName={USERNAME})(cn={USERNAME}))(objectClass=user))"
    useSSL=false;
  sync.LoginModule optional;
};
```

In this example, you should modify the values for the `userProvider`, `authIdentity`, and `userFilter` attributes to suit your environment.

#### Create (or Modify) the JAASRealm Module

Create a context for {siteNameShort} by creating (or modifying, if it is present) the configuration XML file that is located here:

`$CATALINA_BASE/conf/Catalina/localhost/sync.xml`

<Note>Depending on how Tomcat is configured, this path might be slightly different. In this example, `Catalina` refers to the engine name, and `localhost` is the host name that is defined in server.xml.</Note>

Define a `&lt;Context&gt;` block and add a `&lt;Realm&gt;` element as shown below:

```xml theme={null}
<Context>
  <Realm className="org.apache.catalina.realm.JAASRealm" appName="Sync"
    userClassNames="sync.SimplePrincipal"
    roleClassNames="sync.GroupPrincipal" />
</Context>
```

Then, update the `&lt;Host&gt;` element in the server.xml configuration file for the Tomcat server by setting the `copyXML` attribute to `true`, as shown below:

```xml theme={null}
<Host name="localhost" appBase="webapps" unpackWARS="true" autoDeploy="true" copyXML="true">
  ...
</Host>
```

#### Make the Login Module Visible

The Java virtual machine (JVM) must be directed to the login module (jaas.config) for the configuration to be visible. Set the `java.security.auth.login.config` system property on the JVM to the path of the jaas.config file. To do so, append the following line to the `$CATALINA_BASE/conf/catalina.properties` file:

```bash theme={null}
java.security.auth.login.config=${catalina.base}/conf/jaas.config
```

### Configure Data Directory Permissions

Give the user of the process that runs the Java servlet container Read/Write access to the data directory in the appropriate location, as follows:

* **Windows:** `C:\ProgramData\CData\Sync\`
* **Linux:** `~/cdata/sync`

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

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

The syntax for editing the lockout settings in the Tomcat sync.xml file is the following:

```xml theme={null}
<Context>
  <Parameter name="LockoutFailedAttempts" value="0" />
</Context>
```

## Configuration in WebSphere

### Configure the WebSphere Class Loader

For WebSphere to load the application resources correctly, you must follow these steps:

1. Within WebSphere, navigate to **Application > Application Types > WebSphere enterprise applications**.
2. Select **{siteNameShort}**.
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. Click **OK**. Then click **Save**.

### Configure the Java Authentication and Service (JAAS)

The following process is required to configure the JAAS and to enable {siteNameShort} to manage users dynamically in the WebSphere Application Server:

1. Deploy {siteNameShort}:
   1. Enable application security (navigate to **Security > Global security > Enable application security**).
   2. Add the custom login module to the system login, as follows:
      1. Navigate to **Security > Global security > Java Authentication and Authorization Service > System logins > WEB\_INBOUND**. Click **New** to add a new entry named <code>{siteNameShortLower}.LoginModule</code>. Note that the <code>{siteNameShortLower}.LoginModule</code> must appear before `com.ibm.ws.security.server.lm.ltpaLoginModule`.
      2. Select the **Use login module proxy** check box.
      3. Select **OPTIONAL** under **Authentication strategy**.
      4. Add **isWebSphere** under **Custom properties** and set it to **true**.
2. Create groups:
   1. Navigate to **Users and Groups > Manage Groups > Create**.
   2. Create **{companyNameLower}\_admin**, **{companyNameLower}\_standard**, and **{companyNameLower}\_support** groups.
3. Map groups to roles:
   1. Navigate to **Applications > Application Types > WebSphere enterprise applications > {siteNameShortLower}\_war > Security role to user/group mapping**.
   2. Map the **{companyNameLower}\_admin** group to the **{companyNameLower}\_admin** role.
   3. Map the **{companyNameLower}\_standard** group to the **{companyNameLower}\_standard** role.
   4. Map the **{companyNameLower}\_support** group to the **{companyNameLower}\_support** role.
   5. Map **All Authenticated in Application's Realm** to the **{companyNameLower}\_user** role.
4. Set the `com.ibm.ws.webcontainer.AllowQueryParamWithNoEqual` property to **true**:
   1. Navigate to **Server > Server Types > Web Sphere Application Servers** and select the server on which {siteNameShort} is hosted.
   2. Select **Container Settings > Web Container Settings > Web Container**.
   3. Select **Additional Properties > Custom Properties**.
   4. Add this new property: `com.ibm.ws.webcontainer.AllowQueryParamWithNoEqual`
   5. Set the value to **true**.
5. Restart WebSphere.

### Configure Data Directory Permissions

Give the user of the process that runs the Java servlet container Read/Write access to the data directory:

* **Windows:** `C:\ProgramData\CData\Sync\`
* **Linux:** `~/cdata/sync`

Restart the WebSphere server for the changes to take effect. You can now log into the application.

## Configuration in Jetty

Although {siteNameShort} comes with an embedded Jetty web server, you can also use the application with an external Jetty setup.

### Deploy the WAR File

Copy the WAR file into Jetty's `webapps` folder.

### Configure the Java Authentication and Service (JAAS)

To configure the JAAS and to enable {siteNameShort} to manage application users, you must perform the steps that are described in the following subsections.

#### Add the JAAS Module

Submit the following command to install the JAAS module:

```bash theme={null}
java -jar {JETTY_HOME}/start.jar --add-to-start=jaas
```

#### Create the Login Module

Create a login configuration file with the name login.config in this folder: `{JETTY_BASE}/etc/login.conf`

Place the following content in the login.config file:

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

#### Update the Security Handler

The Security Handler configuration is in the sync.xml configuration file. Modify the `securityHandler` block as follows:

```xml theme={null}
<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>
          <!-- LoginModuleName must match the name of your LoginModule, as declared in your login-module configuration file. -->
       <Set name="loginModuleName">Sync</Set>
       <!-- Set the principal class name for the custom role. -->
       <Set name="roleClassNames">
           <Array type="java.lang.String">
             <Item>sync.GroupPrincipal</Item>
           </Array>
         </Set>
     </New>
   </Set>
  </New>
</Set>
```

### Configure Data Directory Permissions

Give the user of the process that runs the Java servlet container Read/Write access to the data directory:

* **Windows:** `C:\ProgramData\CData\Sync\`
* **Linux:** `~/cdata/sync`

Restart the Jetty server for the changes to take effect. You can now log into the application.

## Configure 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.

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 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 that is used. Using the syntax that is appropriate for the specific servlet, the `AppDirectory` environment variable must be set to the path of the directory that you want.

If {siteNameShort} can locate the `AppDirectory` 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 {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)

Starting with version 26.2, {siteNameShort} uses an embedded H2 database as the default application database. Existing installations continue to use the legacy embedded Derby database. {siteNameShort} does not automatically migrate existing installations to H2.

You can also configure {siteNameShort} to use an enterprise database, such as Microsoft SQL Server, PostgreSQL, or MySQL. 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).

### Configure the Database Connection

When you use {siteNameShort} with an external Java servlet (any server other than the Jetty server that is included with the application), the details for configuring the application database depend upon the specific servlet that is used. Using the syntax that is appropriate for the specific servlet, choose either of the following approaches to use when you configure the server:

* Define a JNDI data source to include the connection properties for the target database.
* Set the `APP_DB` environment variable to a JDBC connection string.

If {siteNameShort} can use the JDNI data source or the `APP_DB` connection string to {siteNameShortLower} to a database, it uses that database as the application database.

### Protect Your Database Credentials with an Encrypted Connection String

{siteNameShort} provides the ability to generate an encrypted connection string for your application database connection. You can use this encrypted connection string to specify the application database without storing your login credentials in plaintext in the {siteNameShort} properties file.

To generate an encrypted connection string, issue the following command in the installation directory where {siteNameShortLower}.jar is located, substituting your connection information for the example string in quotation marks:

```bash theme={null}
java -jar sync.jar -EncryptConnectionString "jdbc:cdata:mysql:Server=serverName;Port=1234;Database=databaseName;User=userName;Password=passwordSample"
```

After you issue the command, the command window prints the encrypted string, as shown in this example:

```bash theme={null}
ENCRYPTEDA:5TWyjE0U4GBEVNkd51SqbMXaBwVGqj5uyMfTHt48y/F5l3sDPZynNnPMb/ppXzuFTzFPywA1/SSKUgLy9nAuvA7RAdZj7WsKI1xAgDMmEFNQ68/lHjFYZpS10sIaoUloyZVDkj4uLHTZ0SaMD5PPUA==
```

You can use this encrypted string in place of the plaintext value for `cdata.app.db` when you configure the application database with the methods [explained earlier](#configure-the-database-connection).