Working with Proxy Servers

When using the ESB profile of WSO2 Enterprise Integrator (WSO2 EI), there can be scenarios where you need to configure the ESB to route messages through a proxy server. For example, if the ESB is behind a firewall, your proxy service might need to talk to a server through a proxy server as illustrated in the following diagram:

For such scenarios, you need to configure the ESB transport sender to forward messages through a proxy server.

Routing messages through a proxy server

See the instructions given below.

For non-blocking service calls

To configure the ESB profile to route messages through a proxy server (for non-blocking service calls), add the parameters given below to the axis2.xml file (stored in the <EI_HOME>/conf/axis2/ directory) and update the values. This configuration ensures that all HTTP requests pass through the configured proxy server.

<transportSender name="http" class="org.apache.synapse.transport.passthru.PassThroughHttpSender">    
    <parameter name="non-blocking" locked="false">true</parameter>
    <parameter name="http.proxyHost" locked="false"></parameter>
    <parameter name="http.proxyPort" locked="false"></parameter>
</transportSender>

The parameters are described below.

non-blocking	Specifies whether or not 'non-blocking' mode is enabled for the transport sender. Be sure that this parameter is set to `true`.
http.proxyHost	The host name of the proxy server.
http.proxyPort	The port (number) in the proxy server.

For blocking service calls

To configure the ESB profile to route messages through a proxy server (for blocking service calls), add the parameters given below to the axis2_blocking_client.xml file (stored in the <EI_HOME>/conf/axis2/ directory) and update the values. This configuration ensures that all HTTP requests pass through the configured proxy server.

<parameter name="Proxy">
     <parameters>
       <ProxyHost></ProxyHost>
       <ProxyPort></ProxyPort>
       <ProxyUser></ProxyUser>
       <ProxyPassword></ProxyPassword>
     </parameters>
</parameter>

The parameters are described below.

ProxyHost	The host name of the proxy server.
ProxyPort	The port (number) in the proxy server.
ProxyUser	The user name for connecting to the proxy server.
ProxyPassword	The password for connecting to the proxy server.

Bypass the proxy server for blocking calls?

In the case of blocking service calls, you can apply a system property in the ESB profile to bypass the proxy server and route messages directly to the hosts that should receive the messages. Explained below are two methods of applying the system property:

Set the system property in the product startup script that is located in the <PRODUCT_HOME>/bin/ directory as shown below. Note that the list of host names are separated by the pipe symbol ('|').
```
-Dhttp.nonProxyHosts =10.|localhost|127.0.0.1|.\.domain.com \
```

Pass the system property when you start the server as shown below.

./integrator.sh -Dhttp.nonProxyHosts =10.|localhost|127.0.0.1|.\.domain.com

A proxy server might require HTTP basic authentication before it handles communication from the ESB profile.

Configuring proxy profiles in the ESB profile

When using the ESB profile, there can be scenarios where you need to configure multiple proxy servers to route messages to different endpoints as illustrated in the following diagram.

proxy profile

When you need to route messages to different endpoints through multiple proxy servers, you can configure proxy profiles.

To configure proxy profiles in the ESB profile:

Edit the <EI_HOME>/conf/axis2/axis2.xml file, add the proxyProfiles parameter in the <transportSender> configuration of the http transport, and then define multiple profiles based on the number of proxy servers you need to have.

When you define a profile, it is mandatory to specify the targetHosts, proxyHost and proxyPort parameters for each profile.

The following is a sample proxy profile configuration that you can have in the <transportSender> configuration of the HTTP transport:

<parameter name="proxyProfiles">
      <profile>
          <targetHosts>example.com, .*.sample.com</targetHosts>
          <proxyHost>localhost</proxyHost>
          <proxyPort>3128</proxyPort>
          <proxyUserName>squidUser</proxyUserName>
          <proxyPassword>password</proxyPassword>
          <bypass>xxx.sample.com</bypass>
      </profile>
      <profile>
          <targetHosts>localhost</targetHosts>
          <proxyHost>localhost</proxyHost>
          <proxyPort>7443</proxyPort>
      </profile>
      <profile>
          <targetHosts>*</targetHosts>
          <proxyHost>localhost</proxyHost>
          <proxyPort>7443</proxyPort>
          <bypass>test.com, direct.com</bypass>
      </profile>
 </parameter>

When you configure a proxy profile, following are details of the parameters that you need to define in a <profile>:

Parameter	Description	Required
`targetHosts`	A host name or a comma-separated list of host names for a target endpoint. Host names can be specified as regular expressions that match a pattern. When `targetHosts` is specified as an asterisks (*), it will match all the hosts in the profile	Yes
`proxyHost`	The host name of the proxy server.	Yes
`proxyPort`	The port number of the proxy server.	Yes
`proxyUserName`	The user name for the proxy server authentication.	No
`proxyPassword`	The password for the proxy server authentication.	No
`bypass`	A host name or a comma-separated list of host names that should not be sent via the proxy server. For example, if you want all requests to `*.sample.com` to be sent via a proxy server, but need to directly send requests to `hello.sample.com`, instead of going through the proxy server, you can add `hello.sample.com` as a bypass host name. You can specify host names as regular expressions that match a pattern.	No