Using JaxView Agent Stubs

About JaxView Agent Stubs

When using an agent stub monitoring deployment, you will need to install a small jar file at the server or container where the Web service to be monitored is running. This agent handler tells the Web service container to forward a copy of service messages to the agent stub. The agent stub then forwards the message copies to the JaxView management server.

Once installed, JaxView agent stub configurations can be managed centrally through the JaxView interface. This requires an additional configuration action when installing the stub on the application server or container.

An added option that can be performed by JaxView agent stubs is LDAP authentication for service requests arriving at the server or container. This is an alternative to using JaxView as a service gateway for centralized security services.

This document provides a description of how to work with JaxView agent stubs and how to configure these options.

Configuring JaxView Stubs

There are three main steps for using agent stubs to collect Web service message data for JaxView:

Install agent stubs package on Web service application servers
Configure the Web service server to recognize and use the stub
Add Agent Stub connection objects to JaxView

Installing Agent Stubs on Web Service Application Servers

JaxView agent stubs must be installed on the servers where the Web service applications are running. The stubs are designed to be installed in the application container (servlet or context container). The steps you use are similar for different containers. The following are the servlet containers that are currently supported by JaxView. Click on the name of the application type you need to monitor for more information on how to install the agent stub and configure the application server to use the stub.

If you don't see the container type that you need, please contact support@managedmethods.com and we'll help you install a Stub on this container.

Adding Stub Connection Objects to JaxView

After you have installed the agent stubs on the application servers, you must configure JaxView to connect to the stubs to receive messages. You do this by adding a Agent Stub connection definition object to the Admin object tree in JaxView. See the Administration Options section for more information on how to configure the agent stub connection definition in JaxView.

Once JaxView has established communication with the remote agent stub, the stub will be able to forward service messages to JaxView for monitoring and alerting. If you have configured the agent stub for remote management by JaxView

Configure Remote Agent Stub Management

Starting with JaxView 3.3, agent stubs can be configured to allow remote management via the JaxView interface. The steps you use to configure the agent stub for remote management from JaxView include the steps you use to install the agent stubs plus some additional configuration actions. The following describes this process.

Copy the agent stub file to the application server where the Web services to be monitored are running.
Configure the application server to use the agent stub for sending messages to JaxView as described in the previous sections. See the sections for the specific server product for more detailed information.
In addition, you must configure the application server to run a small communication servlet that will be used by JaxView to manage the agent stub remotely. See the section below for an example using a J2EE servlet container.
Add the agent stub connection information into JaxView using the Admin tab as described in the section Adding Stub Connection Objects to JaxView
Repeat these steps for each remote agent stub to be used.
After adding agent stub connection information to JaxView, you use the Stub node in the Admin tab to view and edit the configuration information for the selected remote agent stubs.

The following are examples of the parameters you use to configure an application server or servlet container to enable remote management of JaxView agent stubs. In this example you would modify the web.xml file for a J2EE server and add following identifiers for the JaxView stub servlet. This will instruct the server to run a servlet with which JaxView can use to communicate with the agent stub.

Add the following servlet declaration:

 <servlet>
   <servlet-name>StubServlet</servlet-name>
   <servlet-class>com.hubble.clientservice.StubServlet</servlet-class>
 </servlet>

Add the following servlet-mapping section:

 <servlet-mapping>
     <servlet-name>StubServlet</servlet-name>
     <url-pattern>/servlet/StubServlet</url-pattern>
 </servlet-mapping>

Save the changes. It may be necessary to restart the server for the changes to be recognized by the server.

Configure Stub Authentication

JaxView agent stubs can be used to provide LDAP authentication services for the Web services being monitored. Incoming service requests are handled by the agent stub which can then query a directory service to authenticate the credentials of the service requester. This is an alternative to using JaxView as a services authentication gateway and central policy management application.

Note: This option is not currently available for .NET servers.

To enable service authentication by the agent stub, you use the steps described in the section Configure Remote Agent Stub Management. Once JaxView has established communication with the agent stub, you use the Stub node in the Admin tab of JaxView to configure the authentication settings for the agent stub.

Agent Stub Authentication Properties

The following describe the agent stub authentication properties. For more information on the options for authentication, see the section Applying Policies to Services in JaxView.

authenticateRequest: This value must be set to "true" in order to enable authentication.
ldapProvider: Set this equal to the LDAP provider URL. For example: ldap://ldap.managedmethods.com:389
ldapSecurityPrincipal: Set this equal to the LDAP security principal. For example: uid=testid,ou=test,o=ManagedMethods. See the section LDAP/AD Authentication for use of the [USER_ID] substitution variable to capture the username in requests.
ldapSearchFilter: Set this to be the search filter expression for the user name in the requests. For example (objectClass=user)(uid=[USER_ID]) where [USER_ID] is a variable that will be replaced by the username from the request.
ldapDefaultPassword: Set this equal to the password for above security principal, if applicable.
requestUserNameExpression: Set this equal to the XPath expression or regular expression that JaxView should use to extract the username in the request messages. Where the username is contained inside a SOAP envelope element Prefix the expression with the string “XPATH:”. This also could be a regular expression which will extract the username out of the header or the body of the request. See the section JaxView Tools for examples of regular expression syntax.
requestPasswordExpression: Set this equal to the XPath to get to the Password from requests. JaxView will then replace the password before saving message to disk This also could be a regular Expression which will extract the password out of the header or the body of the request.
rootDN: If applicable, set this equal to the root security principal or distinguish name to search under for the user in the incoming request.

Configuring Agent Stub Authentication Manually

Agent stubs can be configured manually to perform authentication services without enabling the remote configuration management option. This may be necessary if organizational policies do not allow for the activation of the agent stub remote communication servlet. Use the following steps to configure each agent stub.

To configure stub authentication manually

Use the steps described in the section Configuring JaxView Stubs to install the agent stub on the application server.
After the agent stub has been activated on the Web service application server, the agent stub will create a properties file on the local file system. Locate the file jv.properties on the application server machine.
Open the jv.properties with a text editor.
Edit the file to include the applicable settings needed to connect to the directory service. See the section Agent Stub Authentication Properties for a description of the properties.
Optionally, you may change the value of the JVConfigFilePath property to a different file path location. This property defines the location of the properties file to the agent stub. Be sure to save the updated properties file to the corresponding location.
Save the changes