Search

Java

Version 22.0.8473

Java

The Java edition of CData Arc includes an embedded Eclipse Jetty web server so that you can run Arc 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.

The embedded Jetty server requires that JDK 11 or later is installed on the machine. Deploying to an external Java servlet container requires Servlet 3.0 (Jetty 8+, Tomcat 7+, WebSphere 8+, and so on).

Note: No matter how you choose to deploy Arc, the files and folders within 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 cdataarc as this user.

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

sudo chown -R cdataarc:cdataarc /opt/arc

Using the Embedded Jetty Server

To start the embedded Jetty server, simply run the arc.jar file that resides in the Arc installation directory (InstallationDirectory). This directory also contains a service script, which you can use to set up a systemd or init.d service in UNIX operating systems.

By default, the embedded server hosts Arc on port 8080, and it only accepts plain-text connections (HTTP but not HTTPS).

After you start the server, access the web UI by directing a browser to http://localhost:8080. The application prompts you to create username and password credentials for the first user of the application. This user will have the role of admin.

Changing the Port

To configure the port on which the embedded server listens:

  1. Locate the arc.properties file in the installation directory and open it in a text editor.

  2. Locate the line where CData.http.port is set:

     cdata.http.port=8080

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

Enabling SSL/TLS

To enable SSL/TLS connections (HTTPS), you also need to modify the arc.properties file in the installation directory 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} may be used to refer to the installation directory.
  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. Optionally, set cdata.http.port 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 Arc, be sure to change the owner of the certificate to the service account that is used to host Arc (cdataarc:cdataarc).

Starting and Stopping the Server

If you use the service script to set up an Arc service, see Running as a Service. Otherwise, the Running In-Process section is applicable.

Running In-Process

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

java -jar arc.jar

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

java -jar arc.jar -stop

Running as a Service

You can manipulate the Arc service by using standard system service commands, referencing arc as the name of the service.

To start the service, submit this command:

systemctl start arc

To stop the service, submit this command:

systemctl stop arc

To restart the service, submit this command:

systemctl restart arc

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. 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 Arc 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 will be used to start the application.

Using Tomcat

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

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

Configuring the Java Authentication and Service (JAAS)

To enable Arc 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:

Arc {
  arc.LoginModule required;
};

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

Arc {
  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;
  arc.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 Arc by creating (or modifying, if it is present) the configuration XML file that is located here: $CATALINA_BASE/conf/Catalina/localhost/arc.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.

Define a <Context> block and add a <Realm> element as shown below:

<Context>
  <Realm className="org.apache.catalina.realm.JAASRealm" appName="Arc"
    userClassNames="arc.SimplePrincipal"
    roleClassNames="arc.GroupPrincipal" />
</Context>

Then, update the <Host> element in the server.xml configuration file for the Tomcat server by setting the copyXML attribute to true, as shown below:

<Host name="localhost" appBase="webapps" unpackWARS="true" autoDeploy="true" copyXML="true">
  ...
</Host>

Note: If an application-specific context is present in server.xml, it will take precedence over arc.xml. For example:

<Context path="arc">
   ...
</Context>

It is recommended that you relocate any application context overrides, such as APP_DIRECTORY or APP_DB, to arc.xml where JAASRealm is defined.

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:

java.security.auth.login.config=${catalina.base}/conf/jaas.config

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\
  • UNIX or Mac OS X: ~/cdata/arc

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

Using WebSphere

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\
  • UNIX or Mac OS X: ~/cdata/arc Restart the WebSphere server for the changes to take effect. You can now log into the application.

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

Java Authentication and Service (JAAS)

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

  1. Deploy Arc:
    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 arc.LoginModule. Note that the arc.LoginModule 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 cdata_admin, cdata_standard, and cdata_support groups.
  3. Map groups to roles:
    1. Navigate to Applications > Application Types > WebSphere enterprise applications > arc_war > Security role to user/group mapping.
    2. Map the cdata_admin group to the cdata_admin role.
    3. Map the cdata_standard group to the cdata_standard role.
    4. Map the cdata_support group to the cdata_support role.
    5. Map All Authenticated in Application’s Realm to the cdata_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 Arc 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.

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\
  • UNIX or Mac OS X: ~/cdata/arc

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

Using an External Jetty Server

Although Arc 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.

Java Authentication and Service (JAAS)

To configure the JAAS and to enable Arc to manage application users, you must follow the steps that are described in the following subsections.

Add the JAAS Module

Submit the following command to install the JAAS module:

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:

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

Update the Security Handler

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

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

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\
  • UNIX or Mac OS X: ~/cdata/arc

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

Managing Users

Upon initial startup, Arc 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 Arc 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 Arc to manage users. The previous sections detail the process of JAAS configuration for each specific external servlet.

Configuring the Application Directory

The Arc 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 Arc is hosted via the embedded web server or via an external Java servlet container.

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

/opt/arc

When Arc 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 Arc
  • Using a shared network drive for application data
  • Embedding Arc 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 Java edition with the embedded Jetty server, the ApplicationDirectory is configured in the arc.properties file that is found in InstallationDirectory. Within this server configuration file, you must set the cdata.app.directory setting to the path of the desired directory. The following example demonstrates what this might look like when you set the data directory to a shared folder on a mounted drive:

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

If Arc 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.

External Java Server

When you use the Java 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 Arc 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.

Configuring the Application Database

The Arc 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 Arc configuration

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

Embedded Java Server

When you use the Java edition with the embedded Jetty server, the application database is configured in the arc.properties file that resides in the installation directory. 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 sections below provide example connection strings for various server configurations. You can set these values in plaintext as shown below, or you can generate an encrypted connection string to use instead.

MySQL

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

PostgreSQL

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

SQL Server

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

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

Generating an Encrypted Database Connection String

Arc 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 Arc 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 plaintext value for cdata.app.db as shown above.

External Java Server

When you use the Java 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 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 Arc can use the JDNI data source or the APP_DB connection string to connect to a database, it uses that database as the application database.

Setting Login Lockouts

Arc 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 in the arc.properties file by adding a comma-separated list of name:value pairs to initParameters, as shown below:

cdata.initParameters=LockoutFailedAttempts:0

Tomcat

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

<Context>
  <Parameter name="LockoutFailedAttempts" value="0" />
</Context>

Solving Common Issues

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

Failure to Start or Incorrect AppDirectory

Issue

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

Potential Causes

This error might indicate that Arc does not have the permissions that are required to access ApplicationDirectory.(ApplicationDirectory is a folder that stores critical information regarding the configuration of flows, certificates, and so on.) One possible cause for this error is running Arc 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 Arc as a service.

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

sudo chown -R cdataarc:cdataarc /opt/arc