Connecting the integration agent to xMatters web servers via web server proxy

Deprecated!

The features and functionality described in this article have been implemented in the integration agent. For more information, see xMatters integration agent 5.1 patch 1 Release Notes.

Summary

This document describes how to configure the integration agent so that it connects to its primary/secondary xMatters web servers via a proxy server. Proxy servers are commonly used to provide additional security and access control within corporate intranets.

Background

The integration agent's main configuration file, <IAInstall>/conf/IAConfig.xml, contains the URLs of the primary and secondary xmatters web servers to which the integration agent will attempt to connect:

<!--
| These servers are assumed to be connected to the same database.
+-->
<primary-servers>
    <!--
    | 0 or more URL elements that specify the primary location of each server's
    | RegisterIntegrationAgent Web Service.  The URLs must begin with either http:// or https://
    | and cannot have a query or fragment component.  The URLs must be resolvable from this IA.
    +-->
    <url>http://primary1.company.com:8888/api/services/AlarmPointWebService</url>
    <url>http://primary2.company.com:8888/api/services/AlarmPointWebService</url>
    <url>http://primary3.company.com:8888/api/services/AlarmPointWebService</url>
</primary-servers>

<!--
| These servers are assumed to be connected to the same database,
| which can be different than the primary servers' database.
+-->
<secondary-servers>
  <!--
    | 0 or more URL elements that specify the secondary location of each Server's
    | RegisterIntegrationAgent Web Service.  The URLs must begin with either http:// or https://
    | and cannot have a query or fragment component.  The URLs must be resolvable from this IA.
    +-->
    <url>http://secondary1.company.com:8888/api/services/AlarmPointWebService</url>
    <url>http://secondary2.company.com:8888/api/services/AlarmPointWebService</url>
</secondary-servers>

The integration agent's default configuration is to connect directly to these web servers: hostnames are resolved to IP addresses and HTTP or HTTPS connections are established directly to these IP addresses and ports.

The integration agent runs within a Java virtual machine (JVM), which controls how network connections are established.  Most JVM implementations, including the ones packaged with the integration agent, can be configured to establish network connections through a proxy server. Proxied connections are established by specifying system options for the JVM. The specific options vary between JVM vendors, but typically include the following:

  • http.proxyHost
  • http.proxyPort
  • http.nonProxyHosts
  • http.proxyUsername
  • http.proxyPassword

If the integration agent uses HTTPS URLs to connect to xmatters, the corresponding options will begin with https (e.g., https.proxyHost).

For more background on proxy configuration, consult the following URLs:

http://docs.oracle.com/javase/6/docs/technotes/guides/net/proxies.html

Configuration

The system options used by the integration agent's JVM are specified in the integration's wrapper configuration file, <IAInstall>/conf/wrapper.conf, as the values (prefixed with -D) ofwrapper.java.additional.x lines:

# This controls the amount of time (in seconds) that the Wrapper will wait for the IA to start before exiting with an error code.
wrapper.java.additional.4=-Dorg.tanukisoftware.wrapper.WrapperSimpleApp.waitForStartMain=FALSE
wrapper.java.additional.5=-Dorg.tanukisoftware.wrapper.WrapperSimpleApp.maxStartMainWait=120


# This flag is set by mule.sh to turn on 64-bit JVM for HPUX-Itanium, so should not be overwritten
# (i.e., if you need to add another Java parameter, begin with wrapper.java.additional.7)
# wrapper.java.additional.6=-d64


# Set these parameters for your HTTP proxy if behind a firewall

#wrapper.java.additional.3=-Dhttp.proxyHost=proxy.acme.com

#wrapper.java.additional.4=-Dhttp.proxyPort=8080

#wrapper.java.additional.5=-Dhttp.proxyUsername=

#wrapper.java.additional.6=-Dhttp.proxyPassword=

To enable proxied connections, uncomment the corresponding lines that begin with #wrapper.java by removing the hash (#).  The numbers appearing at the end of each line (e.g., 3 inwrapper.java.additional.3) must also be updated so that they begin immediately after the last uncommented wrapper.java.additional.x line.  In the above example, the last uncommentedwrapper.java.addtional.x line is wrapper.java.additional.5, so the file would be modified as follows:

# This controls the amount of time (in seconds) that the Wrapper will wait for the IA to start before exiting with an error code.
wrapper.java.additional.4=-Dorg.tanukisoftware.wrapper.WrapperSimpleApp.waitForStartMain=FALSE
wrapper.java.additional.5=-Dorg.tanukisoftware.wrapper.WrapperSimpleApp.maxStartMainWait=120


# This flag is set by mule.sh to turn on 64-bit JVM for HPUX-Itanium, so should not be overwritten
# (i.e., if you need to add another Java parameter, begin with wrapper.java.additional.7)
# wrapper.java.additional.6=-d64


# Set these parameters for your HTTP proxy if behind a firewall

wrapper.java.additional.6=-Dhttp.proxyHost=proxy.acme.com

wrapper.java.additional.7=-Dhttp.proxyPort=8080

wrapper.java.additional.8=-Dhttp.proxyUsername=

wrapper.java.additional.9=-Dhttp.proxyPassword=

The values of the uncommented wrapper.java.additional.x lines must also be updated to reflect the proper proxy settings.  If a username/password is not required to connect to the proxy server, the corresponding wrapper.java.additional.x lines can remain commented out.

For example, if the integration agent connects to a proxy server with address 192.168.1.1:9998, and proxy authentication is not required, the wrapper.conf file would contain the following settings:

# This controls the amount of time (in seconds) that the Wrapper will wait for the IA to start before exiting with an error code.
wrapper.java.additional.4=-Dorg.tanukisoftware.wrapper.WrapperSimpleApp.waitForStartMain=FALSE
wrapper.java.additional.5=-Dorg.tanukisoftware.wrapper.WrapperSimpleApp.maxStartMainWait=120


# This flag is set by mule.sh to turn on 64-bit JVM for HPUX-Itanium, so should not be overwritten
# (i.e., if you need to add another Java parameter, begin with wrapper.java.additional.7)
# wrapper.java.additional.6=-d64


# Set these parameters for your HTTP proxy if behind a firewall

wrapper.java.additional.6=-Dhttp.proxyHost=192.168.1.1
wrapper.java.additional.7=-Dhttp.proxyPort=9998

#wrapper.java.additional.8=-Dhttp.proxyUsername=

#wrapper.java.additional.9=-Dhttp.proxyPassword=

Troubleshooting

You can see additional information about proxy connections by configuring the integration agent to log debug messages from the Apache software components.

To enable logging of the debug messages:

  1. Make a backup copy of \conf\log4j.xml
  2. Edit as follows:

replace

<logger name="org.apache">  
    <level value="WARN"/>  
  </logger>  

with

<logger name="org.apache">  
    <level value="DEBUG"/>  
  </logger>  

Note: Ensure that this section is not surrounded by a

  1. Save the file

The additional messages will now appear in \log\alarmpoint.txt

Example:

2013-10-23 10:17:38,797 [Heartbeat-1] DEBUG - ProxyConfiguration

2013-10-23 10:17:38,810 [Heartbeat-1] DEBUG - HttpConnectionManager.getConnection: config = HostConfiguration[host=http://10.2.0.121:8888, proxyHost=http://proxy.acme.com:8080], timeout = 0

2013-10-23 10:17:38,811 [Heartbeat-1] DEBUG - Allocating new connection, hostConfig=HostConfiguration[host=http://10.2.0.121:8888, proxyHost=http://proxy.acme.com:8080]

2013-10-23 10:17:38,815 [Heartbeat-1] DEBUG - Open connection to proxy.acme.com:8080

2013-10-23 10:17:41,208 [Heartbeat-1] DEBUG - Closing the connection.

2013-10-23 10:17:41,208 [Heartbeat-1] DEBUG - Method retry handler returned false. Automatic recovery will not be attempted

2013-10-23 10:17:41,210 [Heartbeat-1] INFO - Unable to sendViaPost to urlhttp://10.2.0.121:8888/api/services/AlarmPointWebService

java.net.UnknownHostException: proxy.acme.com

xMatters Reference

DTN-3088, DTN-3414, JDN-3304

Originally created by Stirling Chow

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk