The Ohlon 1.0 Manual

Welcome to the Ohlon Manual! Ohlon is a tool to improve the performance of your Ephesoft servers. It will help you to monitor in real time your servers. But it can be used for reporting purposes or on-going maintenance. This manual will explain you how to install and to configure your Ohlon monitoring tool.

Download

You can download all required files from SourceForge.net:

Download Ohlon

Installation

This section provides instructions to install Ohlon for various systems. We'll explain you how to install the different components of Ohlon. First, let's see what looks like a standard installation:

It's composed of:

  • Ohlon Agent deployed within the Ephesoft engine;
  • Jolokia WAR Agent deployed in the same application server of Ephesoft;
  • Ohlon console.

The Ohlon agent deployed within Ephesoft is a JAR file in charge of exposing properties and methods required by the Ohlon Console over JMX. The Jolokia WAR agent (that needs to be deployed on the same application server than Ephesoft) is a JMX-HTTP bridge. And finally, the Ohlon console is connected to the Jolokia agent over HTTP/S to get information from the Ephesoft server.

Ohlon Agent

The Ohlon agent is a simple JAR file to deploy within your Ephesoft engine. You first need to shutdown your Ephesoft server. Then, just deploy this JAR file within <EPHESOFT_HOME>/Application/WEB-INF/lib. Then, edit the file <EPHESOFT_HOME>/Application/applicationContext.xml and add the following line:

<import resource="classpath:/META-INF/applicationContext-ohlon-jmx.xml" />

This newly added line will load the Ohlon agent during the Ephesoft startup. You can restart your Ephesoft server. From now on, all required methods and properties required by Ohlon are exposed via JMX.

Logger configuration

If you plan to use the Error page in Ohlon, you need to define a new appender in <EPHESOFT_HOME>/Application/log4j.xml:

<appender name="OHLON" class="com.ohlon.ephesoft.logger.OhlonLogger">
    <param name="Size" value="500" />
</appender>

You can notice the parameter called Size. It's used to configure the number of errors stores in memory. If Ephesoft generates more than 500 errors (by default), we'll keep only the most recent ones. This value can be increased or decreased. Then, locate the tag <root> and reference the new appender by adding:

<appender-ref ref="OHLON" />

Jolokia WAR Agent

The goal of the Jolokia WAR agent is to offer a bridge between JMX and HTTP. It can be heavily configured to limit the access of some beans (cf. Jolokia documentation). You can download directly the WAR file directly from the Jolokia website (https://jolokia.org/download.html), and apply all network and security configurations. Or, you can just decide to download our pre-packaged version. This version limits the access only to the features required by the Ohlon console.

First, you need to shutdown your Ephesoft server. Then, copy the jolokia.war file into <EPHESOFT_HOME>/JavaAppServer/webapps. The Ohlon pre-packaged Jolokia WAR file is to configure to use basic authentication. Edit the file <EPHESOFT_HOME>/conf/tomcat-users.xml. Add the new role ohlon:

<role rolename="ohlon" />

In the same file, add a user having this role:

<user username="ohlon" password="YOURPASSWORD" roles="ohlon" >

The newly added user will be the only one allowed to connect to Jolokia. Note that the username ohlon is not required, and you are free to use the username that you want. You can restart your Ephesoft server.

You can check if everything is working properly by open a browser on the following URL: http://[YOUR_EPHESOFT_SERVER]/jolokia/read/java.lang:type=Memory/HeapMemoryUsage. It will display a login prompt where you need to enter the username and the password that you specified above. if everything is working properly, you should get a JSON object looking like that:

{"timestamp":1435242283,"status":200,"request":{"mbean":"java.lang:type=Memory","attribute":"HeapMemoryUsage","type":"read"},"value":{"max":1908932608,"committed":318242816,"init":32871552,"used":174261520}}

Ohlon console

The Ohlon console is a WAR file that needs to be deployed in a Tomcat application server. This documentation doesn't explain how to install Tomcat. You'll be able to find the required steps on the Tomcat website. When Ohlon is deployed, you can restart your server, and open a browser on the following URL: http://[YOUR_OHLON_SERVER]/ohlon. And you should be able to see this homepage:

At this stage, you can login using the username ohlon and the password ohlon. By default, Ohlon is configured to connect to one of Ohlon's demonstration server. After the login page, you should be able to see this page:

Don't panic if you can't see anything, our demo server is maybe shutdown for the moment. I recommend you to continue to the next section to understand how to connect your Ohlon console to your Ephesoft server.

Connect to your Ephesoft server

Now, we are going to connect your Ohlon console to your Ephesoft server. You first need to shutdown the Tomcat server containing the Ohlon console. Then, you need to edit the file <OHLON_HOME>/webapps/ohlon/WEB-INF/classes/config/servers.json with:

{
    "servers": {
        "ohlon-demo": {
            "label": "Your Ohlon Server",
            "jolokia": "http://[YOUR_EPHESOFT_SERVER]/jolokia",
            "dcma": "http://[YOUR_EPHESOFT_SERVER]/dcma",
            "data": "http://[YOUR_EPHESOFT_SERVER]/dcma-batches/ephesoft-system-folder",
            "username": "ohlon",
            "password": "YOURPASSWORD",
            "server_name": []
        }
    }
}

You need to replace the URLs depending of your environment, and don't forget to update the password that you defined during the installation of the Ohlon agent. When it's completed, you can restart your Tomcat server and you should be able to monitor your Ephesoft instance.

Upgrade

Upgrade the Ohlon webapp

First, you need to save some configuration files that you may have been customized:
  • <OHLON_HOME>/webapps/ohlon/WEB-INF/classes/config/servers.json
  • <OHLON_HOME>/webapps/ohlon/WEB-INF/spring-security.xml
Then:
  • Stop your Tomcat instance;
  • Delete the Ohlon webapp file: <OHLON_HOME>/webapps/ohlon.war
  • Delete the Ohlon webapp folder: <OHLON_HOME>/webapps/ohlon
  • Upload the new version of the ohlon.war on your server, and move it to the folder <OHLON_HOME>/webapps
If you didn't do any configuration, you can restart your Tomcat instance. Otherwise, you need to decompress your ohlon.war and replace the files that you backup at the beginning.

Upgrade the Ohlon JMX component

First, you need to stop your Ephesoft instance. Then:
  • Be sure to delete all versions of the Ohlon library. Delete all ephesoft-*jmx*.jar in the folder <EPHESOFT_HOME>/Application/WEB-INF/lib;
  • Upload the new version of the library on your server, and move it to the folder <EPHESOFT_HOME>/Application/WEB-INF/lib
You can finally restart your Ephesoft instance.

Configuration

Server(s) configuration

The main configuration point is the file <OHLON_HOME>/webapps/ohlon/WEB-INF/classes/config/servers.json. It contains all information how the Ohlon console will connect to your Ephesoft server(s), but it will configure as well the user interface. As you can easily notified, this file is a JSON object containing at least this structure:

{
    "servers": {
        ...
    }
}

Then, you need to define at least one server. But this file can contains more than one. The key used within the servers will represent the server identifier that must be unique:

{
    "servers": {
        "unique_id_1": {},
        "unique_id_2": {},
        ...
    }
}

For each server, you need to define a new JSON object that contains these keys:

  • label contains the name displayed in the Ohlon console;
  • jolokia contains the URL to connect to the Jolokia WAR agent. Because, this agent has to be deployed on the same application server than Ephesoft, the protocol, the host and the port is the same as Ephesoft;
  • dcma contains the URL to connect to Ephesoft;
  • data contains the URL to access files stored within Ephesoft (used by the folder explorer page);
  • username contains the username to connect to Jolokia. This parameter is optional, if it's not specified, Ohlon will send queries without any authentication;
  • password contains the password to connect to Jolokia. This parameter is optional;
  • server_name is represented as an array. It contains string values representing the server name. This information is used by the page 'Server Status' to identify when the server is running. You can see below how to get this information.
  • pages is represented as an array. It contains string values representing the pages that you want to enable. This parameter is optional.

The next question is how to find out the server names related to my Ephesoft server. To achieve that, you'll need to connect to your Ephesoft reporting database, and execute the following query:

mysql> SELECT DISTINCT server_name FROM `server_status`;
+----------------------+
| server_name          |
+----------------------+
| myephesoft:8080/dcma |
+----------------------+

The query can returned more than one value, in the case of a clustered environment. But it can happen as well if your changed the name of your server, or change the listening port of Ephesoft.

Here is the list of valid values for the parameter pages:

  • live that enables the page called Live;
  • error that enables the page called Error;
  • reporting that enables the page called Analysis;
  • batchclass that enables the page called Batch Class;
  • batchinstance that enables the page called Batch Instance;
  • user that enables the page called Manual Steps;
  • serverstatus that enables the page called Server Status.

Note that if the parameter pages doesn't exist or is empty, all pages will be enabled by default.

Here is what should look like a simple configuration file:

{
    "servers": {
        "ephesoft-prod": {
            "label": "Ephesoft - Production",
            "jolokia": "http://www.mycompany.com/jolokia",
            "dcma": "http://www.mycompany.com/dcma",
            "data": "http://www.mycompany.com/dcma-batches/ephesoft-system-folder",
            "username": "ohlon",
            "password": "mysecretpassword",
            "server_name": [ "ephesoft-server:80/dcma" ]
        }
    }
}

Notification configuration

The configuration for the notification component is saved in the file <OHLON_HOME>/webapps/ohlon/WEB-INF/classes/config/application.properties.

Ohlon is able to send notifications based on 4 different events:

  • When a batch instance is ready for review;
  • When a batch instance is ready for validation;
  • When a batch instance is in error status;
  • When Ohlon can't connect to Ephesoft (to identify if the server is not running anymore).

For each event, it's possible to send the notification via email and/or using PushBullet. PushBullet is a free service to connect to multiple devices, including phones (Android, iPhone, BlackBerry, WindowsPhone), browsers (Chrome, Firefox, Opera, Safari) and even your operating system (Windows and Mac). Using this system, you can easily receive Ohlon notifications on your phone and on your workstation screen. The next section will provide more details how to configure the PushBullet service. Here is the list of available parameters:

Property name Default value Description
notification.enabled true Indicates if the notification system is enabled or not
notification.startup.enabled true Indicates if we should send notifications at the startup of the server
notification.cron */30 * * * * ? CRON expression used to check Ephesoft applications
notification.status.readyforreview email|pushbullet Indicates which system should be used when a batch instance is ready for review
notification.status.readyforvalidation email|pushbullet Indicates which system should be used when a batch instance is ready for validation
notification.status.error email|pushbullet Indicates which system should be used when a batch instance is in error status
notification.server email|pushbullet Indicates which system should be used when a server is not running

Email configuration

You can configure the connection to your SMTP server using these parameters:

Property name Default value Description
notification.email.enabled false Indicates if the email notification system is enabled or not
notification.email.host smtp.email.com SMTP server host
notification.email.port 25 SMTP server port
notification.email.protocol smtp SMTP protocol
notification.email.username SMTP username
notification.email.password SMTP password
notification.email.from noreply@ohlon.com Sender's email address

Then, for each notification (including readyforreview, readyforvalidation, error, server), you can configure these different properties:

  • recipient: contains the list of emails (separated by ;) that will receive the email;
  • title: contains the email subject (can contain the variable $identifier or $server);
  • template: contains the path to the Freemarker template that will used for the email body.

All Freemarker template, stored in the folder <OHLON_HOME>/webapps/ohlon/WEB-INF/classes/templates/email, can be easily customized. When the template is used for the generation of the email body, Ohlon provides variables:

  • identifier: batch instance identifier (not valid for the notification server);
  • status: batch instance status (not valid for the notification server);
  • date: current date;
  • url: link to Ephesoft (not valid for the notification server);
  • server: server label (valid only for the notification server).

PushBullet configuration

As explained above, PushBullet is a free service used to send notifications to different devices including phone, workstation or browser. Only 2 parameters are provided to configure globally the PushBullet service:

Property name Default value Description
notification.pushbullet.enabled false Indicates if the PushBullet notification system is enabled or not
notification.pushbullet.token Access token required to authenticate to PushBullet

To obtain a PushBullet access token, you'll need to create a PushBullet account. When it's created, open the My Account page, and scroll down to the section "Access Token" that will display your unique access token:

Then, for each notification (including readyforreview, readyforvalidation, error, server), you can configure these different properties:

  • devices: contains the list of device identifier (separated by ;) that will receive the notification;
  • emails: contains the list of email addresses, used during the PushBullet account creation, (separated by ;) that will receive the notification;
  • title: contains the notification title (can contain the variable $identifier or $server);
  • body: contains the notification body (can contain the variable $identifier or $server);

Note that the parameter devices will be used in priority, if both parameters devices and emails are configured.

To be able to use the devices parameter, you'll need to get the identifier of your devices. You just need to login to your PushBullet account, and then, click on one of your devices. You can get device identifier from the URL:

Authentication

Ohlon is configured by default to use basic authentication. The only available username is ohlon. You can easily switch to LDAP by editing the file <OHLON_HOME>/webapps/ohlon/WEB-INF/spring-security.xml. Just comment the basic authentication configuration:

<authentication-manager>
  <authentication-provider>
    <user-service>
      <user name="ohlon" password="ohlon" authorities="ROLE_USER" />
    </user-service>
  </authentication-provider>
</authentication-manager>

And, then uncomment the LDAP configuration piece:

<ldap-server id="ldapServer" url="ldap://yourldap.com:389/dc=mycompany,dc=com" />

<beans:bean id="customAuthoritiesPopulator" class="com.ohlon.security.CustomLdapAuthoritiesPopulator" />

<beans:bean id="ldapAuthProvider" class="org.springframework.security.ldap.authentication.LdapAuthenticationProvider">
  <beans:constructor-arg name="authenticator">
    <beans:bean class="org.springframework.security.ldap.authentication.BindAuthenticator">
      <beans:constructor-arg ref="ldapServer" />
      <beans:property name="userSearch">
        <beans:bean class="org.springframework.security.ldap.search.FilterBasedLdapUserSearch">
          <beans:constructor-arg name="searchBase" value="ou=users" />
          <beans:constructor-arg name="searchFilter" value="(uid={0})" />
          <beans:constructor-arg name="contextSource" ref="ldapServer" />
        </beans:bean>
      </beans:property>
    </beans:bean>
  </beans:constructor-arg>
  <beans:constructor-arg name="authoritiesPopulator" ref="customAuthoritiesPopulator" />
</beans:bean>

<authentication-manager>
  <authentication-provider ref="ldapAuthProvider" />
</authentication-manager>

Ohlon is a Spring based application, so you'll find the required documentation on the Spring website.