This article covers the setup requirements to install XRay, Navigator, and Security Manager into an existing Apache Tomcat implementation.

Jump ahead Installing XRay into Apache Tomcat Xray.war file Setting up Tomcat properties in Catalina.sh Configuring Tomcat Server.xml (Optional) Reviewing Context.xml Installing Navigator and Security Manager into Apache Tomcat Install Navigator and Security Manager into Tomcat Navigator Initial Setup Updating Security Manager and Navigator Validating Access Validate XRay Access Validate Security Manager Access Validating Navigator Access

 

Installing XRay into Apache Tomcat

Xray.war file

Place xray.war in the <Tomcat_home>\webapps folder.  The app server will create the \xray directory structure.

Setting up Tomcat properties in Catalina.sh

There are four Tomcat properties that must be set up in Catalina.sh. These properties are used as parameters when the server is started. 

The table below shows which properties are required by XRay version.

	Required 1.4	Required 1.5
-Djkool.service.conn.str ActiveMQ Address	X	X
-Djkool.stream.url Streaming URL	X	X
-Djkool.administrator.token Administrator Root Token		X
-Dtnt4j.default.event.factory tnt4j Logging	X	X

 

ActiveMQ Address

XRay reads messages from ActiveMQ and executes them. The ActiveMQ address is specified as shown below:

JAVA_OPTS=”$JAVA_OPTS -Djkool.service.conn.str=123.16.6.210:61616”

Streaming URL

The following streaming URL must be specified if you plan to import data from .CSV, .XLS/XLSX (Microsoft® Excel), Apache log, or other custom file formats into XRay using the user interface Import Data wizard.

Typically this URL uses the HTTP or HTTPS protocols.

JAVA_OPTS=”$JAVA_OPTS -Djkool.stream.url =http://123.16.6.210:6580”

Ports used: 6580 or 6585

Administrator Root Token (XRay 1.5 and later)

The administrator root token is only required for versions 1.5 and later. It is used to create an authenticated connection.

JAVA_OPTS=”$JAVA_OPTS -Djkool.administrator.token=1298eae0-b27c-4175-9081-aa665c49e653”

Configure tnt4j Logging

To configure tnt4j log files, use the following. This step also applies to Navigator.

JAVA_OPTS=”$JAVA_OPTS -Dtnt4j.default.event.factory=com.jkoolcloud.tnt4j.sink.impl.slf4j.SLF4JEventSinkFactory”

 

Configuring Tomcat Server.xml

This section contains examples for deploying the xray.war and jkool-server.war web applications by configuring the Apache Tomcat server.xml file using <Context> XML elements.

Context Element Example: xray.war

The following example shows how to configure the Apache Tomcat server.xml file using the <Context> XML element for xray.war. 

<Context path="/jkool-service"
 reloadable="true"
 docBase="jkool-service.war">

 <!-- Client is using ActiveMQ to communicate w/ jKool Service -->

 <!-- The brokerURL host name or IP address should be that of the jKool Service (which is hosting ActiveMQ broker) -->

 <Resource name="jms/FPConnectionFactory"
   auth="Container"
   type="org.apache.activemq.ActiveMQConnectionFactory"
   factory="org.apache.activemq.jndi.JNDIReferenceFactory"
   brokerURL="failover:(tcp://<activeMQBRK1>:61616,tcp://<activeMQBRK2>:61616)?randomize=false&timeout=10000&nested.connectionTimeout=120000&nested.wireFormat.maxInactivityDuration=300000&nested.wireFormat.maxInactivityDurationInitalDelay=60000"/>

 <!-- ActiveMQ queue on which to send requests - physicalName must match definition on jKool Service -->

 <Resource name="jms/queue/client-requests"
  auth="Container"
  type="org.apache.activemq.command.ActiveMQQueue"
  factory="org.apache.activemq.jndi.JNDIReferenceFactory"
  physicalName="jkool.service.requests"/>

 <!-- ActiveMQ queue on which to send admin requests - physicalName must match definition on jKool Service -->

 <Resource name="jms/queue/admin-requests"
  auth="Container"
  type="org.apache.activemq.command.ActiveMQQueue"
  factory="org.apache.activemq.jndi.JNDIReferenceFactory"
  physicalName="jkool.service.admin.requests"/>

 <!-- ActiveMQ queue on which to send update requests - physicalName must match definition on jKool Service -->

 <Resource name="jms/queue/update-requests"
  auth="Container"
  type="org.apache.activemq.command.ActiveMQQueue"
  factory="org.apache.activemq.jndi.JNDIReferenceFactory"
  physicalName="jkool.service.update.requests"/>

 <!-- ActiveMQ topic on which to send status requests - physicalName must match definition on jKool Service -->

 <Resource name="jms/topic/status-requests"
  auth="Container"
  type="org.apache.activemq.command.ActiveMQTopic"
  factory="org.apache.activemq.jndi.JNDIReferenceFactory"
  physicalName="jkool.service.status.requests"/>

</Context>

Context Element Example: jkool-service.war

The following example shows how to configure the Apache Tomcat server.xml file using the <Context> XML Element for jkool-service.war.

<Context path="/jkool-service"
 reloadable="true"
 docBase="jkool-service.war">

 <!-- Client is using ActiveMQ to communicate w/ jKool Service -->

 <!-- The brokerURL host name or IP address should be that of the jKool Service (which is hosting ActiveMQ broker) -->

 <Resource name="jms/FPConnectionFactory"
   auth="Container"
   type="org.apache.activemq.ActiveMQConnectionFactory"
   factory="org.apache.activemq.jndi.JNDIReferenceFactory"
   brokerURL="failover:(tcp://<activeMQBRK1>:61616,tcp://<activeMQBRK2>:61616)?randomize=false&timeout=10000&nested.connectionTimeout=120000&nested.wireFormat.maxInactivityDuration=300000&nested.wireFormat.maxInactivityDurationInitalDelay=60000"/>

 <!-- ActiveMQ queue on which to send requests - physicalName must match definition on jKool Service -->

 <Resource name="jms/queue/client-requests"
  auth="Container"
  type="org.apache.activemq.command.ActiveMQQueue"
  factory="org.apache.activemq.jndi.JNDIReferenceFactory"
  physicalName="jkool.service.requests"/>

 <!-- ActiveMQ queue on which to send admin requests - physicalName must match definition on jKool Service -->

 <Resource name="jms/queue/admin-requests"
  auth="Container"
  type="org.apache.activemq.command.ActiveMQQueue"
  factory="org.apache.activemq.jndi.JNDIReferenceFactory"
  physicalName="jkool.service.admin.requests"/>

 <!-- ActiveMQ queue on which to send update requests - physicalName must match definition on jKool Service -->

 <Resource name="jms/queue/update-requests"
  auth="Container"
  type="org.apache.activemq.command.ActiveMQQueue"
  factory="org.apache.activemq.jndi.JNDIReferenceFactory"
  physicalName="jkool.service.update.requests"/>

 <!-- ActiveMQ topic on which to send status requests - physicalName must match definition on jKool Service -->

 <Resource name="jms/topic/status-requests"
  auth="Container"
  type="org.apache.activemq.command.ActiveMQTopic"
  factory="org.apache.activemq.jndi.JNDIReferenceFactory"
  physicalName="jkool.service.status.requests"/>

</Context>

 

Context Element Example: Connector settings

For XRay and Navigator, specific <Connector> element settings are expected in the server.xml file. 

<Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443" />

<!-- TO Enable SSL connection: -->
 <!--

   <Connector
           protocol="org.apache.coyote.http11.Http11NioProtocol"
           port="8443" maxThreads="200"
           scheme="https" secure="true" SSLEnabled="true"
           keystoreFile="/opt/nastel/AutoPilotM6/ssl/your.jks" keystorePass="password"
           clientAuth="false" SSLProtocol="TLSv1.2"
     />

  -->

(Optional) Reviewing Context.xml

After XRay.war has been extracted, you can find context.xml located at \xray\META-INF\context.xml. This context file includes properties for cache settings and the location of the SAML SSO configuration file. Additional Single Sign-On setup is required. For assistance in setting up Single Sign-On, contact meshIQ support at support@meshiq.com.

1. Place the context.xml file in the $CATALINA_HOME/conf directory. In this location, it will take precedence over the context.xml located in the xray.war file.
2. Review the cachingAllowed and cacheMaxSize settings in this file. An example is provided below.
3. If you are implementing Single Sign-On, follow the steps below. Otherwise, no changes to the xray.samlsso.manager.config property are required.
4. Place the SSO configuration file (xray_samlsso.xml) in the expected system location, which is the Tomcat config directory. For example: $CATALINA_HOME/conf/xray_samlsso.xml.
5. Identify the SSO Configuration file in the context.xml
   1. In the $CATALINA_HOME/conf directory, Edit the file using the local text editor.
   2. Add the following lines into the context.xml file within the XML element <Context>:

<!--samlsso configuration file -->
<Parameter name=”xray.samlsso.manager.config” value=”${catalina.home}/conf/xray_samlsso.xml”/>

Context.xml Example

<?xml version="1.0" encoding="UTF-8"?>

<!--
Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-->

<!-- The contents of this file will be loaded for each web application -->

<Context>

<!-- Default set of monitored resources. If one of these changes, the -->
<!-- web application will be reloaded. -->
<WatchedResource>WEB-INF/web.xml</WatchedResource>
<WatchedResource>WEB-INF/tomcat-web.xml</WatchedResource>
<WatchedResource>${catalina.base}/conf/web.xml</WatchedResource>

<!--samlsso configuration file -->
<Parameter name="apwmq.samlsso.manager.config" value=”${CATALINA_HOME}/conf/apwmq_samlsso.xml”/>
<Parameter name="xray.samlsso.manager.config" value="${CATALINA_HOME}/conf/xray_samlsso.xml"/>

<!-- Uncomment this to disable session persistence across Tomcat restarts -->
<!--
<Manager pathname="" />
-->

<Resources
cachingAllowed="true"
cacheMaxSize="100000"
/>

</Context>

 

Installing Navigator and Security Manager into Apache Tomcat

This section covers the setup requirements to install Navigator into an existing Apache Tomcat implementation.

The following sections cover installation of the web applications integrated with Navigator:

• Navigator Security Manager provides a user interface for defining authorization rules for Navigator.  It allows you to manage authority records and preserve them in the SQL database.
• Navigator provides the ability to view objects and manage messages for Kafka, Solace, TIBCO EMS, IBM MQ, and IIB/ACE.

Install Navigator and Security Manager into Tomcat

The following steps are common to both Navigator and Security Manager.  When finished with these steps, perform the instructions in Set up Users and Roles for the Security Manager.

In the following installation steps, $CATALINA_HOME denotes the directory where Tomcat is installed on your system, such as /nastel/AutoPilotM6/apache-tomcat. 

To install web applications, assuming you are installing in the same apache-tomcat as shipped with AutoPilotM6, do the following:

1. Stop Apache Tomcat Web Server.
2. From webapps, copy the navigator.war, navigator-server.war, apodwsm.war, and navxwsm.war files into the $CATALINA_HOME/webapps  directory.
3. Navigate to $CATALINA_HOME/conf/ and open the file server.xml.
   If not already there, insert the content of APWMQ_HOME/webapps/config/tomcat/DataSource_Snippet_<DATABASE>.xml within the <GlobalNamingResources>...</GlobalNamingResources> block and update the fields indicated according to the database configuration of your machine.
4. Replicate the existing global resource for nastel_permv3_db_ds changing the name to nastel_apwmq_db_ds and changing the database instance to point to the apwmq database.  See the example below.
5. Copy the appropriate JDBC connectors into $CATALINA_HOME/lib by copying the respective JDBC jar from AUTOPILOT_HOME/lib or by downloading the required JDBC driver from the vendor website.
6. Restart Apache Tomcat Web Server.

Example:

<GlobalNamingResources>
. . .
<Resource name="jdbc/nastel_permv3_db_ds"
        scope="Shareable"
                   type="javax.sql.DataSource"
        maxWait="5000"
        maxActive="100"
        maxIdle="100"
        username="user"
        password="pwd"
        url="jdbc:mysql://localhost:3306/nastel_permv3?autoReconnect=true"
        driverClassName="com.mysql.jdbc.Driver"
        auth="Container"/>
<Resource name="jdbc/nastel_apwmq_db_ds"
        scope="Shareable"
                    type="javax.sql.DataSource"
         maxWait="5000"
         maxActive="100"
         maxIdle="100"
         username="user"
         password="user"
         url="jdbc:mysql://localhost:3306/nastel_apwmq?autoReconnect=true"
         driverClassName="com.mysql.jdbc.Driver"
         auth="Container"/>
. . .
</GlobalNamingResources>'

Set up Users and Roles

To access the Navigator Security Manager, users must set up an m6admin role. 

1. Navigate to [CATALINA_HOME]/conf/ and open the file tomcat-users.xml.
2. Add the m6admin role and create or modify users to assign the new role to them as follows:

 <role rolename="m6admin"/>
 <user username="<YOUR-USERNAME>" password="<YOUR-PASSWORD>" fullName="" roles="m6admin"/>

For example:

 <?xml version='1.0' encoding='utf-8'?>
 <tomcat-users>
                <role rolename="tomcat"/>
                <role rolename="manager"/>
                <role rolename="m6admin"/>
  <user username="admin" password="<YOUR-PASSWORD>" roles="m6admin,manager"/>
 </tomcat-users>

All users who are assigned an m6admin role can now access Navigator Security Manager.

Navigator Initial Setup

Licensing Information

Navigator is a standard component of AutoPilot M6 for middleware.  The number of users that can use this interface is limited by the terms of your license.

Connecting to the Network

As part of creating an initial database or upgrading from previous releases, a set of WGS connections was created. You may need to modify these for your environment. Adding and editing workgroup servers can only be performed by administrators with the Configure Connections permission enabled (set in Navigator Security Manager). 

Click the Manage Workgroup Servers button in the Workgroup Servers viewlet located on the WorkSpace dashboard to add a new workgroup server connection or to edit an existing one.

The Work Group Server Connections window opens, displaying all workgroup server connection names and their servers on the left side of the window (this list is global to all administrators).  Select a workgroup server to display its details on the right side of the window. 

If you are upgrading, you might want to delete miscellaneous workgroup server connections that are not used.  The Viewlet Count field on the below screen will help you determine which workgroup servers are no longer needed.  This field displays how many viewlets a workgroup server contains.  Before deleting a workgroup server, you can reassign its viewlets to a different workgroup server.  After moving the viewlets to a new workgroup server, you can then delete the old workgroup server.

Use the Add, Modify and Delete buttons to update the workgroup server connections.  These actions are all audited in the Navigator Security Manager under Administration > Audit Report.  You can view who performed the action, when, and the changes made.

When deleting workgroup server connections, all associated viewlets (both visible and invisible) are deleted.  Before permanently deleting a connection, you can preserve its viewlets by moving them to a different workgroup server.  See Reassigning Viewlets in the Navigator Workgroup Server Expert Installation Guide for more information.  Before workgroup server connections are deleted, a prompt will appear confirming the delete action.  Please note, you will not be able to delete all connections; at least one connection must remain.

The connection names, servers list and port numbers of workgroup servers must be specified when creating a new workgroup server connection. 

The connection name is a custom name to represent the workgroup server connection.  Enter a simple name that will be easy for users to recognize as this name will be displayed in Navigator. 

If you are upgrading, you will need to modify the Connection Names to be something more useful, as these fields were automatically populated after upgrading. 

Please note, the Server(s) list can contain any valid IP or hostname and they must be separated by a comma, for example:  127.0.0.1, 172.16.6.25, NODESERVER1, 172.16.6.44

The Viewlet Count field located on the right side of the window represents all valid viewlets belonging to that connection, it is the total “Favorite Viewlet Count” + “Search Viewlet Count.”

Updating Security Manager and Navigator

If a fix contains the web applications, these must be copied to the application server.  The process to do this is dependent on the application server. For example, to use the Apache version supplied with AutoPilot, do the following:

1. Stop the application server.
2. Copy the war files from the hot fix or e-fix (update) package folder to the <CATALINA_HOME>/apache-tomcat/webapps folder.
3. Remove the existing navigator, navigator-server, and navxwsm folders from <CATALINA_HOME>/apache-tomcat/webapps.
4. Remove the existing navigator, navigator-server, and navxwsm folders from <CATALINA_HOME>/apache-tomcat/work/Catalina/localhost. 

Validating Access

This section describes how to validate access to XRay, Navigator, and Security Manager.

For information about troubleshooting each product, refer to the corresponding FAQ sections in the Resource Center:

XRay FAQ page	https://customers.meshiq.com/hc/en-us/sections/360005390773-Frequently-Asked-Questions
Navigator and Security Manager FAQ page	https://customers.meshiq.com/hc/en-us/sections/360004994474-Frequently-Asked-Questions To troubleshoot access to the Navigator X Security Manager, see https://customers.meshiq.com/hc/en-us/articles/5151491232915-Troubleshooting-Navigator-X-Web-Security-Manager-Login-Issues.

Validate XRay Access

To access the XRay UI from a web browser, use the following address:

http://<serverip>:8080/yourorgname/login.jsp

Use the following log in credentials:

User Name: Admin

Password: admin

Validating with the Default Repository

If the preconfigured standalone appliance configuration is used, the below screen will appear.  By default, the DefaultRepo repository will be loaded with a preconfigured dashboard named test.

Validating with a New Repository

If a new repository has been created, the below screen will display.  The new repository will be loaded with a prompt to create a new dashboard.      

On the Create New Dashboard prompt, enter a name within the Dashboard Name field, select the Two Columns layout and uncheck the Generate Initial Viewlets checkbox. Click Create.

A new dashboard named Test, with no viewlets, is displayed:

Right-click on the dashboard tab, and select Save to save the new dashboard:

Click OK on the following prompt:

To create a viewlet, click the blue Viewlet button located at the top right of the screen.

Select Create Viewlet with jKQL and click create:

Within the Define Query field, enter ‘Get Events’.  The UI will create a default viewlet name.  Click Create.

With the new viewlet created, open the drop-down menu and select Save Viewlet.

Click OK on the following prompt to save the viewlet.

Right-click on the dashboard tab again and select Assign to Teams to modify permissions of the ‘Administrators’ team.

Validate Security Manager Access

Navigator is compatible with both the original Security Manager and the new Navigator X Security Manager.

To access the Security Manager, do the following:

1. Open the link: http://[Host Name or IP address]:[port]/apodwsm or http://[Host Name or IP address]:[port]/navxwsm.

               (example: http://127.0.0.1:8080/apodwsm or http://127.0.0.1:8080/navxwsm)

               The login screen is displayed.

Access to Security Manager is controlled by the underlying application server security.  See the corresponding administration guide for the application server on how to enable user permissions and groups. 

2. Enter the following:

• • User ID
  • Password

On the original Security Manager, you can use Reset to clear the entry fields, if required.

 

3. Click Login.  On the original Security Manager, the start screen is displayed.  On the Navigator X Security Manager, the Manage Users page is displayed.

Validating Navigator Access

After successful deployment, the web application can be accessed using the following URL:

http://<machine_name>:8080/navigator/

Workgroup server authentication is used when logging into the application. The login/password pair must be defined with appropriate group permissions. Enter the following: 

• User ID:  Admin assigned user ID.
• Password:  Admin assigned password.
• Domain: Admin assigned domain.  Only complete this field if instructed to do so by your administrator.

Click LOGIN to enter the application.

Connecting to the Network

If this is the first time you are logging into Navigator and your Administrator has not yet assigned connections, the Connect to WGS window will appear.  This is where you select the environments you to want to log into.

If there are issues logging into one of the selected environments, go to Failed Connection for more information.

Select Different Workgroup Server

Users can select different connection environments in which they want to work in.  Do this by clicking the Add button  located at the top-left of the Workgroup servers viewlet.

The Connect to WGS window opens (this is the same window displayed when logging in with no specified connections, as shown in the previous Connecting to the Network section).  All connections available to the user are displayed.  The check mark represents the environment that the user is currently connected to.  Select all desired connections and click Save changes.  Navigator will now connect to the selected environments.

Failed Connection

When logging into Navigator and there are connection issues to the currently selected workgroup servers, the Connection Selection window displays listing all other available connections.  On this window the user can select the connections to reconnect to.  If the selected connections are successful then they will be remembered as this user’s selected connections.

If any of the connections return an error, a window will appear asking the user to re-enter their credentials.