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

# Cross-Platform Edition

> How to install, configure, and run CData Arc's Cross-Platform edition with embedded Jetty, Tomcat, WebSphere Liberty, or external Jetty.

export const companyName = "CData";

export const siteNameShort = "Arc";

export const siteName = "CData Arc";

The Cross-Platform edition of {siteName} includes an embedded Eclipse Jetty web server so that you can run {siteNameShort} without any external server configuration. In addition, the installation includes a WAR file that can be deployed to any Java servlet container like Apache Tomcat, Eclipse Jetty, or IBM WebSphere Liberty.

{siteNameShort} requires that Java 17 or newer is installed on the machine. Deploying to an external Java servlet container requires Servlet 3.0 (Jetty 8+, Tomcat 7+, WebSphere Liberty 8.5+, and so on).

<Note>
  No matter how you choose to deploy {siteNameShort}, the files and folders in `AppDirectory` must be readable and writable by the user who runs the application. The service installer that is included with the Java Edition setup uses **cdatarc** as this user.

  If the application was run previously as a different user and you want to restore the necessary permissions for a **cdatarc** user to run the application, you should use a command similar to this example:

  `sudo chown -R cdatarc:cdatarc /opt/arc`
</Note>

## Windows

In Windows, {siteNameShort} 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 {siteNameShort} admin console by opening a web browser and entering [http://localhost:8080/](http://localhost:8080/) 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 any 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 {siteNameShort} installer creates start menu shortcuts that allow you to easily use the application. To access these shortcuts, open the **Start** menu and expand the {siteName} folder. These shortcuts are available:

* **Launch {siteName} Admin Console**: Opens a web browser window in your default web browser to the admin console URL, [http://localhost:8080/](http://localhost:8080/). If the service is not running, the web browser returns an error.
* **Start {siteName}**: Starts the {siteNameShort} 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 {siteNameShort} service. This action is necessary when you [upgrade {siteNameShort}](./how-to-upgrade).

#### 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**. Right-click the service to access options to **Start**, **Stop**, and **Restart** it.

#### Command Prompt

Advanced users can use a 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 Arc`).

<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 {siteNameShort} service, issue this command:

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

Use the following commands to restart or stop the service:

```sh theme={null}
arc.exe --restart --ServiceName "CData Arc"
arc.exe --stop --ServiceName "CData Arc"
```

### Launching Without the Service

To run {siteNameShort} 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 arc.jar
```

## Linux

After you [install {siteNameShort} to a location of your choice](./installation-configuration#cross-platform-edition), you can run {siteNameShort} 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 {siteNameShort} as a service enables the application to run independently from any user process and to restart automatically upon rebooting. This is the preferred method for critical applications.

{companyName} recommends creating a daemon to manage the {siteNameShort} 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 {siteNameShort} daemon is to run the script that is included in the installation package, provided that the system uses the *systemd* daemon manager:

```bash theme={null}
bash ./service.sh
```

This script creates a daemon called `arc.service`. You can then use `systemctl` to manage the daemon:

```bash theme={null}
systemctl enable arc
systemctl start arc
```

### Running the Standalone Application

To start {siteNameShort} without creating a service, use the terminal to open the arc.jar file in the installation directory with a configuration file argument, as shown here:

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

## Configuring the Embedded Jetty Server

{siteNameShort} 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 arc.properties file](#generating-the-arc-properties-file) in the {siteNameShort} installation directory (for Windows, this is `C:\Program Files\CData\CData Arc` by default).

For details on all of the `arc.properties` configuration options, see [arc.properties Configuration](./arc-properties-configuration).

<Tip>These configuration options are available in all `.properties` files in your implementation.</Tip>

### Generating the arc.properties File

Before you can make any customizations to the embedded Jetty server, you must create the `arc.properties` file. Run the following command in the installation directory where arc.jar is located:

```
java -jar arc.jar -GenerateProperties
```

This creates the `arc.properties` file in the installation directory. The file contains parameters that you can modify to [change the port](#changing-the-port) or to [enable TLS/SSL](#enabling-tls/ssl).

<Note>Once you have generated this file, upgrades to {siteNameShort} do not overwrite it.</Note>

#### Changing the Port

To change the port on which the embedded server listens:

1. Locate the `arc.properties` file in *`InstallationDirectory`* and open it in a text editor.

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

   `cdata.http.port=8080`

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

#### Enabling TLS/SSL

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

1. Set the `cdata.tls.keyStoreType` setting to the type of keystore to use. Valid values include **jks**, **pkcs12**, and **jceks**.

2. Set the `cdata.tls.keyStorePath` setting to the path of the keystore to use. 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 like this:

```
;; 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 {siteNameShort}, be sure to change the owner of the certificate to the service account that is used to host {siteNameShort} (**cdatarc:cdatarc**).</Note>

#### Pointing {siteNameShort} to a Different .properties File

Use the `-config` parameter to point {siteNameShort} to a configuration file other than the default `arc.properties` file. For example, if you run the following command, {siteNameShort} looks for a `test.properties` file:

```
java -jar arc.jar -config test
```

### Generating a Jetty XML File

In most deployments, the `arc.properties` file provides the full range of necessary configuration options for the embedded Jetty server. However, if you require a more complex deployment, you can generate a Jetty XML file that serves as a starting point for further modifications. To generate this file, run the following command in the {siteNameShort} installation directory where arc.jar is located:

```
java -jar arc.jar -GenerateXML
```

When the command completes, the arc.xml configuration file appears in the `webapp` folder. As long as it remains in that folder, it is used to start the application.

### Starting and Stopping the Server

If you use the `service.sh` script to set up an {siteNameShort} service, see [Running as a Service](#running-as-a-service). Otherwise, the [Running In-Process](#running-in-process) section is applicable.

#### Running In-Process

Start the embedded Jetty server by executing the arc.jar file that is extracted from the application download during setup. You can use standard Java syntax, as shown below, to execute this file and start the server:

```bash theme={null}
java -jar arc.jar
```

To stop the server, pass the `-stop` parameter to this command:

```bash theme={null}
java -jar arc.jar -stop
```

#### Running as a Service

You can manipulate the {siteNameShort} service by using standard system service commands, referencing **arc** as the name of the service.

To start the service, submit this command:

```bash theme={null}
systemctl start arc
```

To stop the service, submit this command:

```bash theme={null}
systemctl stop arc
```

To restart the service, submit this command:

```bash theme={null}
systemctl restart arc
```

### Configuring LDAP Authentication

The following steps configure {siteNameShort} to use LDAP to authenticate users if you use the [embedded Jetty web server](#configuring-the-embedded-jetty-server).

#### Configure arc.properties

If it doesn't already exist, [generate the default arc.properties](#generating-the-arc-properties-file) file with the following command:

`java -jar arc.jar -GenerateProperties`

The following mandatory setting instructs the embedded Jetty server to use LDAP for authentication:

`cdata.loginService.ldap.enabled=true`

You might want to section this off inside the file in the same way as other sections:

```
;; LDAP
cdata.loginService.ldap.enabled=true
```

Insert any additional settings that are required by your specific LDAP server, along with the minimum settings required by {siteNameShort}. At a minimum, {siteNameShort} requires the following:

```
cdata.loginService.ldap.hostname
cdata.loginService.ldap.bindDn
cdata.loginService.ldap.bindPassword
```

The full list of available settings is below:

```
cdata.loginService.ldap.userIdAttribute
cdata.loginService.ldap.debug
cdata.loginService.ldap.forceBindingLogin
cdata.loginService.ldap.bindPassword
cdata.loginService.ldap.roleMemberAttribute
cdata.loginService.ldap.useLdaps
cdata.loginService.ldap.roleBaseDn
cdata.loginService.ldap.bindDn
cdata.loginService.ldap.userPasswordAttribute
cdata.loginService.ldap.hostname
cdata.loginService.ldap.userRdnAttribute
cdata.loginService.ldap.roleObjectClass
cdata.loginService.ldap.port
cdata.loginService.ldap.authenticationMethod
cdata.loginService.ldap.userBaseDn
cdata.loginService.ldap.contextFactory
cdata.loginService.ldap.userObjectClass
cdata.loginService.ldap.roleNameAttribute
```

Following is an example of what a complete LDAP section of `arc.properties` might look like:

```
;; LDAP
cdata.loginService.ldap.enabled=true
cdata.loginService.ldap.bindDn="CN=ldapuser,DC=example,DC=org"
cdata.loginService.ldap.hostname="127.0.0.1"
cdata.loginService.ldap.bindPassword="Adminpassword1"

cdata.loginService.ldap.port="1389"
cdata.loginService.ldap.debug=true
cdata.loginService.ldap.authenticationMethod="simple"
cdata.loginService.ldap.userBaseDn="DC=example,DC=org"
cdata.loginService.ldap.userRdnAttribute="cn"
cdata.loginService.ldap.userPasswordAttribute="userPassword"
cdata.loginService.ldap.forceBindingLogin="true"
cdata.loginService.ldap.roleBaseDn="DC=example,DC=org"
cdata.loginService.ldap.roleNameAttribute="cn"
cdata.loginService.ldap.roleMemberAttribute="member"
cdata.loginService.ldap.useLdaps="false"
```

#### Create LDAP Users in {siteNameShort}

In order for users to log into {siteNameShort} via your LDAP server, you must add each LDAP user to {siteNameShort}. This allows {siteNameShort} to cross-reference the user trying to log in with the configured LDAP server. Follow these steps to create each user (see [User Management and Roles](../administration/settings/user-roles) for more details on managing users):

* Start {siteNameShort} and log in as a {siteNameShort} admin user.
* Create all LDAP users who need access to {siteNameShort}. Click the gear icon in the navbar and choose **Users**. The {siteNameShort} users must be identical to the LDAP users. For example, if your LDAP users are `user01` and `user02`, you must use the same usernames in {siteNameShort}.

Once you have added all users, you can stop the application.

#### Test the Configuration

Once you have created the `arc.properties` file with the necessary LDAP settings, added your LDAP users to {siteNameShort}, and confirmed that their configuration is correct based on your LDAP server's requirements, you are ready to test the functionality.

Start {siteNameShort} using `java -jar arc.jar` or by starting the {siteNameShort} service. When you are presented with the login screen, try to log in using one of your LDAP users. Enter the username and password as it exists on the LDAP server (which must be identical to how you entered it in the **Users** section of {siteNameShort}).

The login process checks the logged-in user against the users configured in {siteNameShort} and then against the LDAP server to ensure that the user is present and allowed to access the application. If the configuration was successful, you will be logged into the application as that user.

#### Troubleshooting LDAP Configurations

If you have trouble authenticating to your LDAP server, {companyName} recommends that you test the LDAP connection and filter with <a href="https://directory.apache.org/studio/" target="_blank">Apache Directory Studio</a>. You can apply the same connection settings and search filter to the `arc.properties` or `login.config` files.

##### Creating a Debug Log for Failed Authentication Attempts

You can enable debugging in the `arc.properties` file with this setting: `cdata.loginService.ldap.debug`.

You can also direct additional logging information to the console output and webserver logs. Create a file called `arc.logging.properties` in the same location as the `arc.properties` file and the `webapps` folder in your application installation directory with the following contents:

```
handlers = java.util.logging.ConsoleHandler, arc.ArcRolloverFileHandler
java.util.logging.ConsoleHandler.level = FINE
arc.ArcRolloverFileHandler.filename = yyyy_mm_dd.log
arc.ArcRolloverFileHandler.formatter = java.util.logging.SimpleFormatter
arc.ArcRolloverFileHandler.level = FINE
# Enable LDAP and Jetty JAAS module debug logs
org.eclipse.jetty.jaas.level = FINE
com.sun.jndi.ldap.level = FINE
```

After you restart the service, additional logging regarding the LDAP authentication attempts is output to the console.

## Configuration in 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 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 a 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 200MB 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 guide. This guide uses `arc.xml` to control the configuration of Tomcat and define any context overrides. {companyName} recommends that you use `arc.xml` instead of `server.xml` to control the Tomcat configuration. We also recommend that you relocate any application context overrides, such as `APP_DIRECTORY` or `APP_DB`, to `arc.xml` where the JAASRealm module is defined.

<Note>This is a required first step for any Tomcat setup with {siteNameShort}.</Note>

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

```xml theme={null}
Arc {
  arc.LoginModule required;
};
```

<Note>If you want to use LDAP, continue with the standard login module setup. Once that's complete, follow the steps in [Using LDAP to Authenticate Users](#use-ldap-to-authenticate-users).</Note>

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

1. Check to see whether you have an `arc.xml` file in `$CATALINA_BASE/conf/Catalina/localhost/`. If you do, edit `arc.xml` and add the XML context block below. If `arc.xml` does not exist at that path, you need to create it, then add the XML context block below. This should be the only content in `arc.xml`.

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

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

2. Update the `<Host/>` element in your `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>
   ```

   <Note>
     If an application-specific context is present in `server.xml`, it takes precedence over `arc.xml`. {companyName} recommends using `arc.xml` over `server.xml` for any context overrides. For example:

     ```xml theme={null}
     <Context path="Arc">
        ...
     </Context>
     ```
   </Note>

#### 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 by appending the following line to the `$CATALINA_BASE/conf/catalina.properties` file:

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

#### Use LDAP to Authenticate Users

Before you can configure {siteNameShort} to use LDAP with Tomcat, follow the [Configure the Java Authentication and Service (JAAS)](#configure-the-java-authentication-and-service-jaas) instructions so that you can create your admin user, which is required before you can add LDAP users to {siteNameShort}. Once you have configured the login module and can successfully log into {siteNameShort} as the admin user, follow these steps to configure LDAP support.

1. Log in to {siteNameShort} as the admin user. To create all LDAP users who need access to {siteNameShort}, click the **Settings** gear icon on the navbar and choose **Users**. The {siteNameShort} users must be identical to the LDAP users. For example, if your LDAP users are `user01` and `user02`, you must use the same usernames in {siteNameShort}.

2. Modify the `$CATALINA_BASE/conf/jaas.config` file that you created in [Create the Login Module](#create-the-login-module) to work with your LDAP server. You must add some configuration options to `jaas.config`.

   a. Ensure that the LDAP login module is required by adding `com.sun.security.auth.module.LdapLoginModule REQUIRED`. You also need to make the login module you created previously optional. To do this, set `arc.LoginModule optional;`.

   b. Add the required LDAP module configuration options. At a minimum, the following options are needed: `userProvider`, `authIdentity`, `userFilter` and `useSSL`. The values that you provide for these options are specific to your LDAP server and requirements: consult your server admin and/or your LDAP documentation to determine the values. Here is an example of what you can expect it to look like — notice that `arc.loginModule` is set to `optional` and `com.sun.security.auth.module.LdapLoginModule` is set to `REQUIRED`:

   ```
   Arc {
     com.sun.security.auth.module.LdapLoginModule REQUIRED
       userProvider="ldap://openldap:1389/ou=users,dc=example,dc=org"
       authIdentity="CN={USERNAME},OU=users,DC=example,DC=org"
       userFilter="(cn={USERNAME})"
       useSSL=false;
       debug=false;
     arc.LoginModule optional;
   };
   ```

   <Note>If any value contains the special token `{USERNAME}`, that token is replaced with the supplied username value at login.</Note>

Once you complete these steps, your LDAP users can log into {siteNameShort}.

### 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\Arc\`
* **Linux:** `~/cdata/arc`

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

## Configuration in WebSphere Liberty

To configure {siteNameShort} in WebSphere Liberty, follow these steps.

### Create the {siteNameShort} Application in WebSphere Liberty

<Note>This guide describes a basic installation of {siteNameShort} in Liberty. If you need more of a custom Liberty installation, consult with your internal team to understand what additional settings or options might need to be included.</Note>

1. Download Liberty from <a href="https://openliberty.io/start/" target="_blank">Open Liberty</a> or <a href="https://www.ibm.com/support/pages/240012-websphere-application-server-liberty-240012" target="_blank">WebSphere Application Server Liberty 24.0.0.12</a>. {siteNameShort} expects the Web Profile 8 package.

2. Run this command to create a server named `arc`:
   * Windows: `.\bin\server.bat create arc`
   * Linux: `./bin/server create arc`

3. Copy the arc.war file to the `./usr/servers/arc/apps` directory.

4. If necessary, change the HTTP and HTTPS ports in the `httpEndpoint` element in `./usr/servers/arc/server.xml` (a [sample server.xml file](#sample-server-xml-file) is below).

5. Make any additional configuration application updates by editing the server.xml file.

6. Run this command to start the server:
   * Windows: `.\bin\server.bat start arc`
   * Linux: `./bin/server start arc`

### Sample server.xml File

The following is a sample server.xml file that contains settings that {siteNameShort} needs to run in Liberty. It also contains the settings required for JAAS configuration. The following sections provide more detail on portions of this file.

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<server description="Arc server">
  <!-- Enable features -->
  <featureManager>
    <feature>webProfile-8.0</feature>
  </featureManager>
  <!-- To access this server from a remote client add a host attribute to the following element, e.g. host="*" -->
  <httpEndpoint id="defaultHttpEndpoint" host="localhost" httpPort="9080" httpsPort="9443" />
  <!-- Automatically expand WAR files -->
  <applicationManager autoExpand="true"/>
  <!-- Default SSL configuration enables trust for default certificates from the Java runtime -->
  <ssl id="defaultSSLConfig" trustDefaultCerts="true" />
  <webContainer AllowQueryParamWithNoEqual="true" />
  <webApplication id="arc-app" contextRoot="/arc" location="arc.war">
    <!-- Map role to group -->
    <application-bnd>
      <security-role name="cdata_admin">
        <group name="cdata_admin" access-id="group:defaultWIMFileBasedRealm/cn=cdata_admin,o=defaultWIMFileBasedRealm" />
      </security-role>
      <security-role name="cdata_standard">
        <group name="cdata_standard" access-id="group:defaultWIMFileBasedRealm/cn=cdata_standard,o=defaultWIMFileBasedRealm" />
      </security-role>
      <security-role name="cdata_support">
        <group name="cdata_support" access-id="group:defaultWIMFileBasedRealm/cn=cdata_support,o=defaultWIMFileBasedRealm" />
      </security-role>
      <security-role name="cdata_user">
        <special-subject type="ALL_AUTHENTICATED_USERS" />
      </security-role>
    </application-bnd>
  </webApplication>
  <jaasLoginModule id="arcLoginModule" className="arc.LoginModule" controlFlag="REQUIRED" classProviderRef="arc-app">
    <options isWebSphere="true" />
  </jaasLoginModule>
  <jaasLoginContextEntry id="system.WEB_INBOUND" name="system.WEB_INBOUND" loginModuleRef="arcLoginModule, hashtable, userNameAndPassword" />
  <!-- logging is optional -->
  <logging traceSpecification="com.ibm.ws.security.appbnd.*=all:com.ibm.ws.security.authorization.*=all:com.ibm.wsspi.security.authorization.*=all:com.ibm.ws.security.jaas.*=all:com.ibm.ws.security.auth.context.*=all:com.ibm.ws.webcontainer.*=all:arc.*=all:rssbus.*=all"
    consoleLogLevel="INFO"
    logDirectory="${server.config.dir}/logs"
    messageFileName="messages.log"
    traceFileName="trace.log"
    hideMessageIDs="true"/>
</server>
```

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

The following settings in server.xml configure the JAAS and enable {siteNameShort} to manage users dynamically in the Liberty application server. If you copied the server.xml sample file above, these elements are already present. Otherwise, follow these steps:

1. Configure the {siteNameShort} login module for JAAS authentication by adding the following elements to server.xml:

   ```xml theme={null}
   <jaasLoginModule id="arcLoginModule" className="arc.LoginModule" controlFlag="REQUIRED" classProviderRef="arc-app">
      <options isWebSphere="true" />
   </jaasLoginModule>
   <jaasLoginContextEntry id="system.WEB_INBOUND" name="system.WEB_INBOUND" loginModuleRef="arcLoginModule, hashtable, userNameAndPassword" />
   ```

2. Configure user groups and role mappings in the `webApplication` element of server.xml.

   ```xml theme={null}
   <webApplication id="arc-app" contextRoot="/arc" location="arc.war">
      <!-- Map role to group -->
      <application-bnd>
        <security-role name="cdata_admin">
          <group name="cdata_admin" access-id="group:defaultWIMFileBasedRealm/cn=cdata_admin,o=defaultWIMFileBasedRealm" />
        </security-role>
        <security-role name="cdata_standard">
          <group name="cdata_standard" access-id="group:defaultWIMFileBasedRealm/cn=cdata_standard,o=defaultWIMFileBasedRealm" />
        </security-role>
        <security-role name="cdata_support">
          <group name="cdata_support" access-id="group:defaultWIMFileBasedRealm/cn=cdata_support,o=defaultWIMFileBasedRealm" />
        </security-role>
        <security-role name="cdata_user">
          <special-subject type="ALL_AUTHENTICATED_USERS" />
        </security-role>
      </application-bnd>
   </webApplication>
   ```

   The `application-bnd` section maps {siteNameShort}'s security roles to user groups, controlling what permissions different users have in the application. Each `security-role` element defines one of {siteNameShort}'s permission levels and associates it with a corresponding user group. Make sure you have a `security-role` element for **cdata\_admin**, **cdata\_standard**, **cdata\_support**, and **cdata\_user**.

3. Enable query parameters without equal signs (=) by adding the `AllowQueryParamWithNoEqual` property to the `webContainer` element. This setting allows {siteNameShort} to properly handle certain URL query parameters that don't include an equal sign.

   ```xml theme={null}
   <webContainer AllowQueryParamWithNoEqual="true" />
   ```

4. Restart Liberty.

Now {siteNameShort} is accessible and ready to use with the {siteNameShort} login module. This securely manages users at the application level. To configure LDAP, read the following section.

### Use LDAP to Authenticate Users

Before you can configure {siteNameShort} to use LDAP with Liberty, follow the [Configure the Java Authentication and Service (JAAS)](#configure-the-java-authentication-and-service-jaas-2) instructions to create your local admin user. That user is required before you can add LDAP users to {siteNameShort}. Once you have configured the login module and can successfully log into {siteNameShort} as the admin user, follow these steps to configure LDAP support.

1. Edit server.xml to add the LDAP repository to Liberty.

   1. In the `featureManager` element, add a new feature: `ldapRegistry-3.0`.

      ```xml theme={null}
      <!-- Enable features -->
      <featureManager>
        <feature>webProfile-8.0</feature>
        <feature>ldapRegistry-3.0</feature>
      </featureManager>
      ```

   2. Add the details for your LDAP registry after the `webContainer` element.

      ```xml theme={null}
      <!-- A LDAP registry sample connects to Microsoft Active Directory. The default activedFilters is used here.
           For more ldap types: https://www.openliberty.io/docs/latest/reference/config/ldapRegistry.html
        -->
      <ldapRegistry id="arcLdapRegistry" realm="testADRealm"
                    host="192.168.0.122" port="389" ignoreCase="true"
                    baseDN="CN=Users,DC=ka,DC=com"
                    bindAuthMechanism="simple"
                    bindDN="ka\nancyw"
                    bindPassword ="xA123456"
                    ldapType="Microsoft Active Directory">
      </ldapRegistry>
      ```

   3. Change the `arc.LoginModule` control flag to `OPTIONAL`.

      ```xml theme={null}
      <jaasLoginModule id="arcLoginModule" className="arc.LoginModule" controlFlag="OPTIONAL" classProviderRef="arc-app">
           <options isWebSphere="true" />
      </jaasLoginModule>
      ```

2. Log in to {siteNameShort} as the local admin user. To create your LDAP users in {siteNameShort}, click the **Settings** gear icon in the navbar and choose **Users**. The {siteNameShort} users must be identical to the users in your LDAP server. For example, if your LDAP users are `user01` and `user02`, you must use the same usernames in {siteNameShort}.

3. Save your changes and restart Liberty to complete the process. Once successfully configured, users signing into {siteNameShort} are authenticated via LDAP.

### Debug Settings

The [sample server.xml](#sample-server-xml-file) file includes a comprehensive logging configuration that captures detailed trace information for security, authentication, web container operations, and {siteNameShort}-specific components. This can be useful if you are having configuration issues with LDAP or other settings.

```xml theme={null}
<!-- logging is optional -->
<logging traceSpecification="com.ibm.ws.security.appbnd.*=all:com.ibm.ws.security.authorization.*=all:com.ibm.wsspi.security.authorization.*=all:com.ibm.ws.security.jaas.*=all:com.ibm.ws.security.auth.context.*=all:com.ibm.ws.webcontainer.*=all:arc.*=all:rssbus.*=all"
  consoleLogLevel="INFO"
  logDirectory="${server.config.dir}/logs"
  messageFileName="messages.log"
  traceFileName="trace.log"
  hideMessageIDs="true"/>
```

The `traceSpecification` attribute is set to `all` for several key component groups including security bindings, authorization, JAAS authentication, web container operations, and all {siteNameShort} and RSSBus modules. This configuration provides thorough diagnostic information useful for troubleshooting authentication issues, authorization problems, and application-specific errors. The logs are written to the `${server.config.dir}/logs` directory with separate files for messages (`messages.log`) and trace data (`trace.log`).

For production environments, you might want to reduce the logging verbosity to improve performance and minimize log file growth. To do this, change specific trace specifications from `all` to `info` or remove components you do not need to monitor. For example, if you are not troubleshooting security issues, you could simplify the configuration to `traceSpecification="arc.*=all:rssbus.*=all"` to focus only on {siteNameShort}-specific logging. Conversely, if you need even more detailed diagnostics during troubleshooting, you can temporarily set `traceSpecification="*=all"` to enable comprehensive logging across all Liberty components. Be aware this generates large log files quickly and should only be used for short-term debugging.

### Configure Data Directory Permissions

Give the user of the process that runs the Java servlet container read and write access to the data directory:

* **Windows:** `C:\ProgramData\CData\Arc\`
* **Linux:** `~/cdata/arc`

Restart the Liberty 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 and arc.xml

Copy arc.war into the `webapps` folder of `${JETTY_BASE}`. Also place the arc.xml file in the same `${JETTY_BASE}` folder. If you do not have arc.xml you need to create it. At a minimum, for a standard configuration of Jetty your arc.xml file needs to contain the following content:

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
<Configure id="arcServer" class="org.eclipse.jetty.webapp.WebAppContext">
  <Set name="contextPath">/</Set>
  <Set name="war">/var/lib/jetty/webapps/arc.war</Set>
  <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">ArcRealm</Set>
          <!-- LoginModuleName must match the name of your LoginModule, as declared in your login-module configuration file. -->
          <Set name="loginModuleName">Arc</Set>
          <!-- Set the principal class name for the custom role. -->
          <Set name="roleClassNames">
            <Array type="java.lang.String">
              <Item>arc.GroupPrincipal</Item>
            </Array>
          </Set>
        </New>
      </Set>
    </New>
  </Set>
</Configure>
```

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

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

#### Add the JAAS Module

Submit the following command to install the JAAS module:

```bash theme={null}
java -jar start.jar --add-modules=deploy,jsp,http,jaas
```

#### Create the {siteNameShort} Login Module

Create a login configuration file called login.config and place it at this path: `{JETTY_BASE}/etc/login.conf`. Place the following content in the login.config file:

```
Arc {
    arc.LoginModule required debug=true;
};
```

#### Update the Security Handler

The Security Handler configuration is in the arc.xml configuration file. If you created the arc.xml file using the content in [Deploy the WAR File and arc.xml](#deploy-the-war-file-and-arc-xml), you can skip this step because this change is already present in that content. Otherwise, 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">ArcRealm</Set>
          <!-- LoginModuleName must match the name of your LoginModule, as declared in your login-module configuration file. -->
       <Set name="loginModuleName">Arc</Set>
       <!-- Set the principal class name for the custom role. -->
       <Set name="roleClassNames">
           <Array type="java.lang.String">
             <Item>arc.GroupPrincipal</Item>
           </Array>
         </Set>
     </New>
   </Set>
  </New>
</Set>
```

### LDAP in Jetty

In order to configure LDAP when running {siteNameShort} in Jetty, you need to configure {siteNameShort} to run in Jetty using the standard {siteNameShort} login module. Once {siteNameShort} is up and running in Jetty using the {siteNameShort} login module, follow these steps to configure Jetty to use LDAP for user authentication.

1. Add LDAP Users to {siteNameShort}.
   1. Login as your Admin user to add LDAP users to {siteNameShort}. To create your LDAP users in {siteNameShort}, click the settings gear icon in the navbar and choose **Users**. The {siteNameShort} users must be identical to the users in your LDAP server. For example, if your LDAP users are `user01` and `user02`, you must use the same usernames in {siteNameShort}.
   2. When you have finished, stop {siteNameShort}.

2. Create the JAAS configuration for the Jetty LDAP login module in login.conf.
   1. Open the login.conf file located at `${JETTY_BASE}/etc/login.conf` and add a JAAS configuration for the Jetty LDAP module. A number of configuration settings are available, but the configuration of your JAAS depends on your specific requirements and your LDAP server configuration. Find the list of available JAAS configuration settings in the <a href="https://jetty.org/docs/jetty/10/operations-guide/jaas/index.html#ldaploginmodule" target="_blank">Jetty documentation</a>, as well as below:

      ```
      debug
      useLdaps
      contextFactory
      hostname
      port
      bindDn
      bindPassword
      authenticationMethod
      forceBindingLogin
      userBaseDn
      userRdnAttribute
      userIdAttribute
      userPasswordAttribute
      userObjectClass
      roleBaseDn
      roleNameAttribute
      roleMemberAttribute
      roleObjectClass
      ```

   2. Here is an example of a login.conf file that is configured with an LDAP server. Remember, the required settings and values are dependent on your specific requirements and your LDAP server configuration. To determine the settings and values required for your setup, consult with your LDAP administrator or the documentation for your LDAP server.

      ```
      Arc {
          arc.LoginModule optional debug=true;
          org.eclipse.jetty.jaas.spi.LdapLoginModule optional
          debug="true"
          contextFactory="com.sun.jndi.ldap.LdapCtxFactory"
          hostname="openldap"
          port="1389"
          bindDn="CN=ldapuser,DC=example,DC=org"
          bindPassword="Adminpassword1"
          authenticationMethod="simple"
          forceBindingLogin="true"
          userBaseDn="OU=users,DC=example,DC=org"
          userRdnAttribute="cn"
          userPasswordAttribute="userPassword"
          roleBaseDn="DC=example,DC=org"
          roleNameAttribute="cn"
          roleMemberAttribute="member"
          useLdaps="false";
      };
      ```

      Notice that the `arc.LoginModule` and the `org.eclipse.jetty.jaas.spi.LdapLoginModule` are both set to optional. This allows both login modules to be used when trying to authenticate a user. If one login module fails to authenticate a user, the login falls back to the second module. If both login modules fail to authenticate a user, the login fails altogether.

   3. Once login.conf has been updated with the necessary LDAP configuration, restart {siteNameShort}. If it is configured correctly, your LDAP users can now log into {siteNameShort}.

### 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\Arc\`
* **Linux:** `~/cdata/arc`

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

## User Management

Upon initial startup, {siteNameShort} prompts you for the creation of a user with username and password credentials. After the first user is created, you can add, delete, and manage users on the **Users** tab of the **Settings** page in the application.

When you deploy {siteNameShort} to an external Java servlet (that is, when you **are not** using the embedded server that is included with the application), JAAS configuration is required in order to allow {siteNameShort} to manage users. The previous sections detail the process of JAAS configuration for each specific external servlet.

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

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

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

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:

`~/arc`

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.

### Embedded Java Server

When you use the Cross-Platform Edition with the embedded Jetty server, by default the *`ApplicationDirectory`* is the *`InstallationDirectory`*. To modify this, [generate the arc.properties file](#generating-the-arc-properties-file). Open the file in a text editor, then 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/arc
```

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 in the specified directory.

### External Java Server

When you use the Cross-Platform 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 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 in the specified directory.

## Configure the Application Database

The {siteNameShort} application database stores several tables of application data, including the following:

* Transaction Log: metadata for each transaction that is processed by the application
* Application Log: application-level errors and events
* Access Log: requests to the application's web endpoint
* Audit Log: user-made changes to the {siteNameShort} configuration

By default, {siteNameShort} uses an H2 database that resides in *`ApplicationDirectory`* as the application database. This database is recommended for up to 100,000 transactions. Once you hit that number, {companyName} recommends moving to an external database. You can configure the application to use an enterprise database like SQL Server, PostgreSQL, or MySQL.

<Note>For security reasons, if you ever switch to a different application database, you must run the [integrityResetTampering](../../scripting/operations/op-integrity-reset-tampering) operation to reset the hash chain.</Note>

### Embedded Java Server

When you use the Cross-Platform Edition with the embedded Jetty server, the default application database is an H2 database in the *`ApplicationDirectory`*. To modify this, [generate the arc.properties file](#generating-the-arc-properties-file). Open the file in a text editor, then 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 MySQL, PostgreSQL, and SQL Server:

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

<Note>To reduce the possibility of deadlocks when using SQL Server as your application database, {companyName} recommends that you ensure that READ\_COMMITTED\_SNAPSHOT is enabled.</Note>

### Generating an Encrypted Database 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 plain text in the {siteNameShort} configuration files. To generate an encrypted connection string, issue the following command in the installation directory where arc.jar is located, substituting your connection information for the example string in quotation marks:

```
java -jar arc.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. For example:

```
ENCRYPTEDA:5TWyjE0U4GBEVNkd51SqbMXaBwVGqj5uyMfTHt48y/F5l3sDPZynNnPMb/ppXzuFTzFPywA1/SSKUgLy9nAuvA7RAdZj7WsKI1xAgDMmEFNQ68/lHjFYZpS10sIaoUloyZVDkj4uLHTZ0SaMD5PPUA==
```

You can then use this encrypted string in place of the plain text value for `cdata.app.db` as [shown above](#configure-the-application-database).

### External Java Server

When you use the Cross-Platform Edition 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 one of the following approaches 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 JNDI data source or the `APP_DB` connection string to connect to a database, it uses that database as the application database.

### Specifying the Default Character Set (MySQL only)

For MySQL versions such as MySQL 8.0 and later, the default character set (charset) for the database and its tables is UTF8 (specifically `utf8mb4`). However, in versions of MySQL prior to 8.0, the default charset is typically Latin1, which can cause issues with data that includes characters outside the basic Latin alphabet.

If you use an older version of MySQL you can avoid these problems by configuring the database to use `utf8mb4` instead. You have two ways to make this change: update the existing database directly, or use MySQL's export and import tools to migrate the data to a new UTF8-encoded database.

**Update the Database Directly**

1. Backup the database: `mysqldump -u root -p --default-character-set=latin1 --databases [database name] > backup.sql`

2. Change the default charset to UTF8: `ALTER DATABASE [database name] CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;`

3. Generate SQL statements to change the default charset to UTF8 for all database tables:

   ```
   SELECT CONCAT('ALTER TABLE ', table_name, ' CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;') AS alter_sql
   FROM information_schema.TABLES
   WHERE table_schema = '[database name]' AND table_type = 'BASE TABLE';
   ```

4. Execute the SQL statements generated in the previous step.

**Use the Export and Import Tools**

1. Export the Data Definition Language (DDL) and data:

   ```
   mysqldump -u root -p --default-character-set=latin1 --no-create-info [database name] > data.sql
   mysqldump -u root -p --no-data [database name] > schemas.sql
   ```

2. Change the default charset in schemas.sql from `CHARSET=latin1` to `CHARSET=utf8mb4`.

3. Create a new database with UTF8 as the default charset: `CREATE DATABASE [new database name] CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;`

4. Import to the new database:

   ```
   mysql -u root -p [new database name] < schema.sql
   mysql -u root -p [new database name] < data.sql
   ```

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

### Embedded Jetty Server

You can modify lockout settings by [generating the arc.properties file](#generating-the-arc-properties-file) and adding a comma-separated list of *name:value* pairs to `initParameters`, as shown below:

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

### Tomcat

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

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

## 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 **[arcsupport@cdata.com](mailto:arcsupport@cdata.com)**.

### Issue

#### {siteNameShort} Fails to Start, or It Starts Using an AppDirectory Other Than 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 cdatarc:cdatarc /opt/arc
```