ArcESB AMI Reference

ArcESB supports convenient cloud deployment through the pre-installed ArcESB AMI available on Amazon Marketplace. This page provides information on AMI-specific management tasks for ArcESB.

• Starting and Stopping ArcESB
• Application Directory
  • Data Folder
  • Workspaces Folder
  • DB Folder
  • Lib Folder
  • Webapp Folder
  • Configuring the Application Directory
• Application Database
• Users and Permissions
• ArcESB User and Password
• Ports and SSL
• Enabling HTTP Connections
• Exposing FTP/SFTP/OFTP Ports
• Upgrading
  • Exporting and Importing Configuration Settings
  • Copying All Application Data
• Installing External Connectors

ArcESB is run as a systemd service in an AMI depoyment, rather than in-process. The service definition file can be found here:

/etc/systemd/system/arcesb.service

ArcESB should be started, stopped, and restarted using standard systemd commands:

All of ArcESB's configuration and application data is held in the Application Directory. By default, the Application Directory is located here:

/opt/arcesb

The Application Directory path can be configured via the arcesb.xml file in the webapp folder, as described in the Configuring the Application Directory section.

The data folder in the Application Directory holds all configuration and application data for the default workspace:

• A 'profile.cfg' file containing the application-wide settings in INI format
• A folder for each connector configured in the default workspace, containing the following: a 'port.cfg' file with the connector setttings in INI format, the files sent/received by the connector, and logs for each transaction processed by the connector

The workspaces folder is similar to the data folder, except it contains the connector folders for all non-default workspaces, and it does not contain the 'profile.cfg' file.

The db folder contains the database files for the default Derby database. Note that the application database can be configured to use an external database as described in the next section.

The lib folder is where the application reads external resources, like drivers for connectors that require an external driver. Place .jar or .class resources in this folder and restart ArcESB to allow the application to read these resources.

The webapp folder contains the arcesb.xml file that determines the configuration of the Jetty server hosting the application. This file can be used to change the port the server listens on, enable a plaintext listener (i.e. HTTP instead of HTTPS), and configure any other Jetty server settings.

Additionally, the arcesb.xml file determines the location of the Application Directory and the database connection for the Application Database.

The Application Directory is configured using the arcesb.xml file in the webapp folder, described in the previous section.

To configure the Application Directory to a non-default location, first find the following snippet within the arcesb.xml file:

<!--
  The APP_DIRECTORY setting is used to explicitly configure a path where profile information is stored.
<Call name="setInitParameter">
  <Arg>APP_DIRECTORY</Arg>
  <Arg><SystemProperty name="arcesb.ami.data" default="/var/lib/arcesb"/></Arg>
</Call -->

Uncomment the <Call> tag within this snippet, and fill in the APP_DIRECTORY argument to the desired folder location. For example:

<Call name="setInitParameter">
  <Arg>APP_DIRECTORY</Arg>
  <Arg>/example/path</Arg>
</Call>

By default, ArcESB uses a Derby database for transaction metadata and general application logs. This Derby database is located in the db folder of the Application Directory, as described in the previous section.

ArcESB can be configured to use an external database like MySQL. Similar to configuring the Application Directory, the Application Database is configured in the arcesb.xml file within the webapp folder.

To configure the Application Database, first find the following snippet within the arcesb.xml file:

<!--
  By default, ArcESB will use a local Derby database to store information on transactions
  and application and access logs. The APP_DB setting may be used to configure a database external
  to the application that will be used to store this information.
<Call name="setInitParameter">
  <Arg>APP_DB</Arg>
  <Arg>jdbc:mysql:Server=MySQLServer;Port=3306;Database=mysql;User=user;Password=password</Arg>
</Call> -->

Uncomment the <Call> tag within this snippet, and fill in the APP_DB argument with a connection string for the target database.

The service account under which ArcESB runs is called 'arcesb,' and it belongs to a group also named 'arcesb.'

If the server is started in-process, any files created by that instance of the application will be written as the user that ran the process (the AMI centos image uses 'centos' as the default user). Errors like 'unable to access database,' 'port not found,' or 'cannot find license' might mean that a file in the data directory was written with incorrect privileges. To resolve this issue, run ArcESB as a service and allow the 'arcesb' user to reclaim ownership of the relevant files by running the following command:

When logging into ArcESB's web UI, the default user is 'admin,' and the default password is the same as the instance ID for the EC2 instance hosting the application.

These values can be viewed and edited in the arcesbRealm.properties file in the Application Directory. In this file, the username is the value to the left of the colon and the password is the first value to the right of the colon.

By default, ArcESB listens for SSL connections (HTTPS) on port 8443. ArcESB is unable to bind to the default HTTPS port (443) due to permissions restrictions, so an iptables rule redirects traffic from port 443 to port 8443. No further action is required for standard HTTPS traffic to reach ArcESB's web server.

ArcESB AMIs include a self-signed certificate for use when hosting an SSL server. If the SSL server needs to be hosted using a certificate signed by a Certificate Authority, then the CA should be contacted directly to procure a certificate.

To add a plaintext/non-SSL port (i.e. HTTP instead of HTTPS), you will need to edit the arcesb.xml file (in the webapp folder of the Application Directory) to enable the plaintext listener. Due to permissions restrictions, this listener cannot directly bind to port 80, so it is established on port 8080 and an iptables rule must be established to forward traffic from port 80 to port 8080.

First, find the snippet within the arcesb.xml file that enables the HTTPS listener:

<!-- Set the connectors on the server object -->
<Call name="setConnectors">
  <Arg>
    <Array type="org.eclipse.jetty.server.ServerConnector">
      <!-- Remove this comment to allow plaintext connections.
      <Item>
        <Ref refid="httpConnector" />
      </Item>
      -->
      <Item>
        <Ref refid="httpsConnector" />
      </Item>
    </Array>
  </Arg>
</Call>
<!-- / Set the connectors on the server object -->

Within this snippet, uncomment the <Item> element that references the 'httpConnector' configuration.

Then, create a new iptables rule to forward traffic from port 80 to port 8080:

iptables -t nat -I PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 8080
/usr/libexec/iptables/iptables.init save

Finally, restart the ArcESB service so that the above changes come into effect.

When ArcESB is used to host an FTP, SFTP, or OFTP server, the port(s) used for protocol traffic must be opened in the AWS firewall. The standard port for each protocol is as follows:

• FTP: 21 (plaintext), 990 (SSL)
• SFTP: 22
• OFTP: 3305 (plaintext), 6619 (SSL)

Note: When hosting an SFTP server, typically a port other than the standard 22 should be used (e.g. 1022). This is because the EC2 instance itself listens for SSH connections on port 22, so the port is not available.

To open one or more of these ports in the AMI, navigate in the AWS management console to Network & Security > Security Groups, select the security group to which the AMI belongs, click Edit inbound rules, and add a new rule for inbound TCP traffic on the desired port. If the IP addresses of the trading partners who will make use of this port is known, specify the list of IP addresses in the 'Source' column of the rule.

Upgrading ArcESB requires launching a new instance of the latest ArcESB AMI. Before launching the new instance, data should be copied over from the old instance so that the application configuration is preserved in the new instance.

There are two approaches to copying over data from the old instance to the new instance:

• Exporting and importing configuration settings only
• Copying all data related to the application, including logs, transaction metadata, and Jetty server configuration.

ArcESB includes a tool to easily export and import the configured connectors/flows in the application. The cogwheel in the top-right of the Flows page includes an 'Export Workspace' option, which simplifies the process of copying configuration settings.

Within the 'Export Workspace' modal, ensure that 'Export all workspaces' 'Include profile info, and 'Export private info' are all checked so that the full application configuration is included in the export. Exporting results in a .arcflow file that can be imported on the new instance. Once the .arcflow file is downloaded, the old instance can be safely decommissioned.

On the new instance, import the configuration settings using the same cogwheel in the top-right of the Flows page: select 'Import Workspace,' then navigate to the .arcflow file downloaded previously.

To preserve logs, transaction metadata, and server configuration along with the application configuration data, it is necessary to copy several folders and files on the filesystem to the new instance.

To accomplish this, follow these steps:

• SSH in to the AMI
• Navigate to the Application Directory, and find the following list of folders and files:
  • data — folder contains connector settings and logs for the default workspace as well as profile settings)
  • workspaces — folder contains connector settings and logs for non-default workspaces
  • db — folder contains the application databases - transaction metadata and general application logging)
  • arcesb.xml file within the webapp — folder contains the Jetty configuration settings for the server hosting ArcESB)
  
  Note that some of these files and folders may not be relevant for every installation. For example, if no changes have been made to the default arcesb.xml file for the Jetty host server, it is not necessary to copy this file over to the new instance.
• Copy over any relevant files and folders to a local machine using SCP (or SFTP), for example:
   cd /opt/arcesb
   scp -r data.
  Once the application files have been copied to a local machine, the old instance can safely be decommissioned.
• Launch the new instance, and connect to it via SSH.
• Using SCP or SFTP, move the local copy of the application folders and files to the new instance — use the same path in the new instance that you had in the old instance.

Some ArcESB connectors are not bundled with the AMI and must be installed externally.

• Download the external connector from https://www.arcesb.com/apps
• SSH into the EC2 instance
• Stop the ArcESB instance with the following command:
   sudo systemctl stop arcesb
• Move the downloaded connector .zip file to the AWS instance via SCP or SFTP
• Extract the connector .zip contents into /opt/arcesb/connectors/
• For the Oracle Connector specifically, the oracle.jdbc.OracleDriver must be visible to the application. Download the JDBC driver from Oracle's website and upload the .jar to /opt/arcesb/lib/
• Set the owner of the deployed resources to the 'arcesb' user, for example:
   sudo chown -R arcesb:arcesb: /opt/arcesb
• Restart the ArcESB service:
   sudo systemctl start arcesb