Java

Version 21.0.7928


Java


The Java edition of includes an embedded Jetty web server so that ArcESB can be run without any external server configuration. In addition, the installation includes a .WAR file that can be deployed to any Java servlet container like Tomcat, Jetty, JBoss, WebLogic, or WebSphere.

The embedded Jetty server requires that JDK 1.8 or later is installed on the machine. Deploying to an external Java servlet container requires Servlet 3.0 (Jetty 8+, Tomcat 7+, JBoss EAP 6/7, Glassfish 3, WebLogic 12+, WebSphere 8+, etc).

Note: No matter how you choose to deploy Arc, the files and folders within AppDirectory must be readable and writable by the user running the application. The service installer included with the Java Edition setup will use ‘arcesb’ as this user.

If the application was previously run as a different user and you wish to restore the necessary permissions for an ‘arcesb’ user to run the application, the command would be something like:

sudo chown -R arcesb:arcesb /opt/arcesb.

Using the Embedded Jetty Server

To start the embedded Jetty server, simply run the arcesb.jar file located in the Arc installation directory. This directory also contains a service script, which may be used to set up a systemd or init.d service on unix systems.

By default, the embedded server hosts Arc on port 8080 and only accepts plaintext connections (HTTP and not HTTPS).

After starting the server, access the web UI by directing a browser to http://localhost:8080. The application will prompt for creating the username/password credentials for the first user of the application (which will have the role of ‘admin’).

Changing the Port

To configure the port that the embedded server listens on, find the ‘arcesb.xml’ file in the installation directory and open it in a text editor. Find the definition of the HTTP connector as indicated by this XML:

<New id="httpConnector" class="org.eclipse.jetty.server.ServerConnector">

Within this definition, modify the following line to change the configured port:

<Set name="port">8080</Set>

Enabling SSL/TLS

Enabling SSL/TLS connections (HTTPS) also involves modifying the ‘arcesb.xml’ file in the installation directory. Find the definition of the HTTP connector:

<New id="httpConnector" class="org.eclipse.jetty.server.ServerConnector">

Within this definition (as a direct child of the above New element), supply an sslContextFactory argument by adding the following XML block:

<Arg name="sslContextFactory">
  <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
    <Set name="KeyStorePath"><SystemProperty name="arcesb.home" default="." />/keystore</Set>
    <Set name="KeyStorePassword">mypassword</Set>
  </New>
</Arg>

Note: The Arg element shown above must be adjacent to other Arg elements at the beginning of the connector definition. This block must not be placed after the Set element that defines the server port, for example.

The KeyStorePath element defines the location of the SSL/TLS certificate used when hosting the SSL/TLS server. The above example assumes that a ‘keystore’ folder has been created in the Arc installation directory and this folder contains a PFX certificate called ‘mycert’. The KeyStorePassword element should be set to the password that corresponds to the configured certificate.

Starting and Stopping the Server

If the service script has been used to set up an ArcESB service, please reference the Running as a Service section below. Otherwise, the Running In-Process section is applicable.

Running In-Process

The embedded Jetty server is started by executing the arcesb.jar file extracted from the application download during setup. Standard Java syntax can be used to execute this file and start the server:

java -jar arcesb.jar

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

java -jar arcesb.jar -stop

Running as a Service

The ArcESB service can be manipulated using standard system service commands, referencing ‘arcesb’ as the name of the service.

To start the service:

systemctl start arcesb

To stop the service:

systemctl stop arcesb

To restart the service:

systemctl restart arcesb

Configuration in Tomcat

Deploy the WAR File

You have several 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 Tomcat documentation covers this method in more detail.

It is possible that the WAR file may 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 may be located 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 200MB WAR file, edit the following values to change the maximum allowed file size:

<multipart-config>
	<!-- 200MB max -->
	<max-file-size>209715200</max-file-size>
	<max-request-size>209715200</max-request-size>
	<file-size-threshold>0</file-size-threshold>
</multipart-config>

JAAS Configuration

In order for Arc to dynamically manage users within the application, JAAS must be configured as described in the following subsections.

Login Module

Create a JAAS configuration file with the name jaas.config located here: $CATALINA_BASE/conf/jaas.config

The content for this file should be as follows:

ArcESB {
    arcesb.LoginModule required;
};

JAASRealm Module

Create a context for ArcESB by creating (or modifying, if it is present) the configuration XML file located here: $CATALINA_BASE/conf/Catalina/localhost/arcesb.xml

Define a Context block and add a Realm element as follows:

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

Then, update the Host element in the server.xml configuration file for the Tomcat server by setting the copyXML attribute to true, like the following:

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

Make the Login Module Visible

The JVM must be pointed towards the Login Module (jaas.config) in order for the configuration to be visible. Set the java.security.auth.login.config system property on the JVM to the path to the jaas.config file. This can be done by appending to the $CATALINA_BASE/conf/catalina.properties file as follows:

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

Configure Data Directory Permissions

Allow the user of the process running the Java servlet container read/write access to the data directory:

  • Windows: C:\\ProgramData\\ArcESB\\
  • Unix or Mac OS X: ~/arcesb/

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

Configuration in JBoss EAP

Note that JBoss AS is not supported.

Deploy the WAR File

There are several ways that you can deploy a WAR file to JBoss:

  • You can copy the WAR file into the JBOSS_HOME/standalone/deployments subfolder.
  • You can also use the JBoss Administration Console to install the WAR file.

JAAS Configuration

In order for Arc to dynamically manage users within the application, JAAS must be configured as described in the following subsections.

Login Module

Edit the standalone.xml configuration file (located here: standalone/configuration/standalone.xml) with a login module as follows:

<subsystem xmlns="urn:jboss:domain:security:2.0">
  <security-domain name="ArcESBRealm" cache-type="default">
      <authentication>
          <login-module code="arcesb.LoginModule" flag="required">
              <module-option name="isJBoss" value="true"/>
          </login-module>
      </authentication>
  </security-domain>
</subsystem>

JBoss Web File

Create a jboss-web.xml file in the WEB-INF folder of the deployment. Set the contents of the file to the following:

<jboss-web>
    <security-domain>java:/jaas/ArcESBRealm</security-domain>
</jboss-web>

Configure Data Directory Permissions

Allow the user of the process running the Java servlet container read/write access to the data directory:

  • Windows: C:\\ProgramData\\ArcESB\\
  • Unix or Mac OS X: ~/arcesb/

Restart the server and log into the application.

Configuration in WebSphere

Configure Data Directory Permissions

Allow the user of the process running the Java servlet container read/write access to the data directory:

  • Windows: C:\\ProgramData\\ArcESB\\
  • Unix or Mac OS X: ~/arcesb/

Restart the server and log into the application.

Configure the WebSphere Class Loader

In order for WebSphere to load the application resources correctly, the following steps are required:

  1. Within WebSphere, navigate to: Application -> Application Types -> WebSphere enterprise applications
  2. Select ArcESB
  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. Select OK -> Save

JAAS Configuration

The following process is required to allow Arc to dynamically manage users in WebSphere Application Server:

  • Deploy ArcESB
  • Enable application security
    • Security → Global security → Enable application security
  • Add custom login module to System Login
    • Security → Global security → Java Authentication and Authorization Service → System logins → WEB_INBOUND → New → arcesb.LoginModule
    • Check the “Use login module proxy”
    • Select OPTIONAL under Authentication strategy
    • Add isWebSphere under Custom properties, set it to true
    • The arcesb.LoginModule must be prior to the com.ibm.ws.security.server.lm.ltpaLoginModule.
  • Create groups
    • Users and Groups → Manage Groups → Create
    • Create arcesb_admin, arcesb_standard, arcesb_support groups
  • Map groups to roles
    • Applications → Application Types → WebSphere enterprise applications → <arcesb_war\> Security role to user/group mapping
    • Map arcesb_admin group to arcesb_admin role
    • Map arcesb_standard group to arcesb_standard role
    • Map arcesb_support group to arcesb_support role
    • Map “All Authenticated in Application’s Realm” to arcesb_user role
  • Set the com.ibm.ws.webcontainer.AllowQueryParamWithNoEqual property to true:
    • Navigate to Server → Server Types → Web Sphere Application Servers, and select the server you are hosting ArcESB on
    • Select Container Settings → Web Container Settings → Web Container
    • Select Additional Properties → Custom Properties
    • Add a new property: com.ibm.ws.webcontainer.AllowQueryParamWithNoEqual
    • Set the value to true.
  • Restart WebSphere

Configuration in WebLogic

Deploy the WAR File

To use the deployment wizard in WebLogic to deploy the WAR file:

  1. Click Deployments
  2. In the Deployments table, click Install.
  3. Enter the path to the WAR file and then select the WAR file from the list.
  4. Select Install this deployment as an application.
  5. Select Custom Roles: Use roles that are defined in the Administration Console; use policies that are defined in the deployment descriptor. Selecting this option allows you to manage the roles and users in WebLogic’s administration console, while WebLogic loads the roles and policies defined in the application.

Configure Data Directory Permissions

Allow the user of the process running the Java servlet container read/write access to the data directory:

  • Windows: C:\\ProgramData\\ArcESB\\
  • Unix or Mac OS X: ~/arcesb/

Restart the server and log into the application.

Configuration in Jetty

While Arc comes with an embedded Jetty web server, the application can also be used with an external Jetty setup.

Deploy the WAR File

Copy the WAR file into Jetty’s webapps folder.

Configure JAAS

The following steps are required to configure JAAS and allow Arc to manage application users.

Add JAAS Module

Run the following command to install the JAAS module:

java -jar {JETTY_HOME}/start.jar --add-to-start=jaas

Create Login Module

Create a login configuration file with the name login.config located here: etc/login.conf

The content for this file should be as follows:

ArcESB {
    arcesb.LoginModule required debug=true;
};

Update the Security Handler

The Security Handler configuration can be found in the arcesb.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">ArcESBRealm</Set>
       <!-- The LoginModuleName must match the name of your LoginModule as declared in your login module configuration file -->
       <Set name="loginModuleName">ArcESB</Set>
       <!-- Set custom role principal class name -->
       <Set name="roleClassNames">
           <Array type="java.lang.String">
             <Item>arcesb.GroupPrincipal</Item>
           </Array>
         </Set>
     </New>
   </Set>
  </New>
</Set>

Configure Data Directory Permissions

Allow the user of the process running the Java servlet container read/write access to the data directory:

  • Windows: C:\\ProgramData\\ArcESB\\
  • Unix or Mac OS X: ~/arcesb/

Restart the server and log into the application.

User Management

Upon first starting, Arc will prompt for the creation of a user with username/password credentials. After this first user is created, users can be added, deleted, and managed via the Settings page of the application, under the Users tab.

When deploying Arc to an external Java servlet (i.e. when not using the embedded server included with the application), JAAS configuration is required to allow Arc to manage users. The sections above detail the process of JAAS configuration for each specific external servlet.

Find and Configure the Application Directory

Arc’s Application Directory holds all of the data used by the application: configuration data, application data, logging data, certificates, etc. The default location of the Application Directory depends on whether Arc is hosted via the embedded web server or an external Java servlet container.

For the embedded web server, the Application Directory is the same as the installation directory, which by default is the following:

/opt/arcesb

When hosting Arc in an external Java servlet container, the Application Directory is relative to the home directory of the user running the server:

~/arcesb (where ‘~’ resolves to the home directory of the user running the server hosting the application)

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

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

Changing the Application Directory will move the application’s data files but will not move other application resources like .exe’s, .jar’s, etc. These resources are held in the Installation Directory, which may be the same as the Application Directory but will not change if the Application Directory is changed.

Embedded Java Server

When using the Java edition with the embedded Jetty server, the application database is configured in the arcesb.xml file found in the Installation Directory. Within this server configuration file, the AppDirectory environment variable must be set to the path to the desired directory. The following example demonstrates what this might look like when setting the data directory to a shared folder on a mounted drive:

<Call name="setInitParameter">
  <Arg>AppDirectory</Arg>
  <Arg>/mnt/shared/arcesb</Arg>
</Call>

If Arc can find the path, and has the appropriate permissions to read and write at the given path, it will create the data folder within the specified directory.

External Java Server

When using 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 used. Using the syntax appropriate for the specific servlet, the AppDirectory environment variable must be set to the path to the desired directory.

If Arc can find the AppDirectory path, and has the appropriate permissions to read and write at the given path, it will create the data folder within the specified directory.

Configure the Application Database

Arc’s Application Database stores several tables of application data, including:

  • Transaction Log (metadata for each transaction 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 Arc’s configuration)

By default, Arc uses a Derby database located in the Application Directory as the Application Database, but this can be configured to use an enterprise database like SQL Server, PostgreSQL, or MySQL.

Embedded Java Server

When using the Java edition with the embedded Jetty server, the application database is configured in the arcesb.xml file found in the installation directory. Within this server configuration file, the APP_DB environment variable must be set to a JDBC connection string containing the appropriate connection parameters for the desired database. For example:

<Call name="setInitParameter">
  <Arg>APP_DB</Arg>
  <Arg>jdbc:mysql:Server=MySQLServer;Port=3306;Database=mysql;User=user;Password=password</Arg>
</Call>

If Arc can successfully establish a connection with the APP_DB connection string, it will use that database as the application database.

External Java Server

When using 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 database depend upon the specific servlet used. Using the syntax appropriate for the specific servlet, one of the following approaches should be used when configuring the server:

  • Define a JNDI datasource 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 datasource or APP_DB connection string to connect to a database, it will use that database as the application database.

Login Lockouts

ArcESB will automatically lock out users who enter incorrect passwords too many times in order to prevent brute force attacks. By default, a user who enters 6 incorrect passwords within 5 minutes will be locked out for 30 minutes.

These settings can be modified by editing the XML configuration file that governs the web server behavior. There are 3 settings relevant to lockouts:

  • LockoutFailedAttempts - the number of incorrect passwords that will trigger a lockout (set this to 0 to disable lockouts)
  • LockoutMinutes - the duration of the lockout (default 30 minutes)
  • LockoutTimeCheckPeriod - the period after which the number of failed attempts is reset to 0 (default 5 minutes)

Embedded Jetty Server

The syntax for editing these settings within the arcesb.xml file for the embedded web server is the following:

<Call name="setInitParameter">
      <Arg>LockoutFailedAttempts</Arg>
       <Arg>0</Arg>
 </Call>

Tomcat

The syntax for editing these settings within Tomcat’s server.xml is the following:

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

Common Issues and Solutions

This section lists common issues encountered when deploying ArcESB in a Java environment. The recommended solution for each issue is included, and for further help please contact support@arcesb.com.

ArcESB fails to start, or starts using an AppDirectory other than what is expected

This error may indicate that ArcESB does not have the permissions required to access the Application Directory (the Application Directory is a folder used to store critical information regarding the configuration of Flows, certificates, etc). Possible causes include running ArcESB as a local user prior to setting it up as a service; in this case, it is possible that certain resources created by the app were created under the local user and are thus not available when running as a service.

Recommended Solution

In Linux, the easiest way to ensure that the service account (or any other account that you want to use to run ArcESB) has access to the Application Directory is to use the chown command. For example, if the Application Directory is in the default linux location and ArcESB should run under the service account, the following command should resolve the error:

sudo chown -R arcesb:arcesb /opt/arcesb