Google Git
Sign in
apache / synapse / 8c14c6aed90c65f1dfd491485272f17dc04b2677 / . / java / modules / documentation / src / site / xdoc / userguide / transports / pass_through.xml
blob: d138814a0ea0c05db7e027dfeeb7811b1ac058eb [file] [log] [blame]
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!--
~ 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.
-->
<document>
<properties>
<title>Apache Synapse - Pass Through HTTP Transport</title>
</properties>
<body>
<section name="Pass Through HTTP Transport" id="Introduction">
<p>
The Pass Through HTTP transport (PTHTTP transport) was developed by
<a href="http://wso2.com">WSO2</a> as a more efficient and more scalable
alternative to the standard Non-blocking HTTP transport (NHTTP transport) of
Synapse. The PTHTTP transport was later contributed to the Synapse project,
and was made the default HTTP transport of the Synapse ESB. All versions of
Synapse released after version 2.1, use the PTHTTP transport by default to
receive and send HTTP messages.
</p>
<p>
The PTHTTP transport was originally designed to facilitate content agnostic (pass
through) HTTP mediation in a highly efficient manner. That is, it mediates
HTTP messages without reading the message body. A number of enterprise integration
scenarios (e.g. header-based routing, load balancing, URL rewriting) require
efficient means of content agnostic mediation, and the standard NHTTP transport of
Synapse is somewhat inefficient when supporting such use cases. The dual-buffer I/O
model of the NHTTP transport induces unnecessary copying of message payload data
between buffers, and it by default parses all received messages using the Axis2
message builder framework. The PTHTTP transport was originally designed with a
single-buffer I/O model, and it skips the Axis2 message builder framework altogether.
Therefore, the PTHTTP transport delivers excellent throughput and minimal latency
when it comes to content agnostic mediation scenarios.
</p>
<p>
However, the original PTHTTP transport did not support any mediation scenario that
requires accessing message payload data (e.g. content-based routing, XSLT
transformation). In order to overcome this limitation, a number of architectural
improvements were introduced to the Synapse mediation engine. These enhancements
enable Synapse to use the PTHTTP transport as the default HTTP transport. Now Synapse
uses a single buffer and does not invoke the Axis2 builders for all content agnostic
mediation flows, but for content-aware mediation flows, it transparently falls back
to the dual-buffer mode and engages the Axis2 message builder framework. Individual
mediators in a message flow (sequence, proxy service) decide whether to invoke the
Axis2 message builders, based on how the mediators intend to process the messages.
This last enhancement, called deferred building, improves the mediation performance
of non-HTTP flows as well.
</p>
<p>
Similar to the NHTTP transport, the PTHTTP transport is also based on the Apache
HTTP Core NIO library. This library is based on the <a href="http://en.wikipedia.org/wiki/Reactor_pattern">reactor pattern</a>,
and the PTHTTP transport uses two separate reactor instances:
<ul>
<li>
Listening I/O reactor: Handles network interactions between client
applications and Synapse.
</li>
<li>
Connecting I/O reactor: Handles network interactions between Synapse and
the backend services.
</li>
</ul>
Each reactor instance uses its own set of threads and in addition, the PTHTTP transport
uses a separate configurable thread pool for processing received messages through
the mediation engine. Settings related to configuring I/O reactor threads and PTHTTP
threads are discussed under <a href="#AdvancedSettings">advanced settings</a>.
</p>
</section>
<section name="Transport Configuration" id="Configuration">
<p>
Pass Through HTTP transport is configured by default in the repository/conf/axis2.xml
file of Synapse. The default configuration activates the following four components:
</p>
<ul>
<li>HTTP transport listener</li>
<li>HTTP transport sender</li>
<li>HTTPS transport listener</li>
<li>HTTPS transport sender</li>
</ul>
<p>
Each of the above components are configured separately in the axis2.xml file. Next
few sections describe the various parameters that can be used to customize the
behavior of these components.
</p>
<subsection name="HTTP Transport Listener" id="HTTPListener">
<p>
The default configuration of the Pass Through HTTP listener is shown
below, as it appears in the axis2.xml file.
</p>
<div class="xmlConf">&lt;transportReceiver name="http" class="org.apache.synapse.transport.passthru.PassThroughHttpListener"&gt;
&lt;parameter name="port"&gt;8280&lt;/parameter&gt;
&lt;parameter name="httpGetProcessor" locked="false"&gt;org.apache.synapse.transport.passthru.api.PassThroughNHttpGetProcessor&lt;/parameter&gt;
&lt;/transportReceiver&gt;</div>
<p>
The default configuration, simply sets the HTTP port to 8280 and specifies the
name of the class responsible for processing incoming HTTP GET requests. A
complete listing of supported parameters is given below.
</p>
<table>
<tr>
<th>Parameter Name</th>
<th>Description/Example</th>
<th>Required</th>
<th>Default</th>
</tr>
<tr>
<td>port</td>
<td>
The port number on which the HTTP listener should listen.
<div class="xmlConf">&lt;parameter name="port"&gt;8280&lt;/parameter&gt;</div>
</td>
<td>Yes</td>
<td>N/A</td>
</tr>
<tr>
<td>bind-address</td>
<td>
The hostname or IP address to which the HTTP listener should bind. When
deploying Synapse on machines that have multiple network interfaces,
this parameter can be used to bind the HTTP listener to a specific network
interface.
<div class="xmlConf">&lt;parameter name="bind-address"&gt;10.0.0.5&lt;/parameter&gt;</div>
</td>
<td>No</td>
<td>All available network interfaces</td>
</tr>
<tr>
<td>hostname</td>
<td>
The hostname or IP address used to calculate the service endpoints
exposed through this transport listener. This can be used to customize
the hostname of the endpoints (EPRs) that appear in the generated WSDLs.
This parameter is ignored if the WSDLEPRPrefix parameter is set.
<div class="xmlConf">&lt;parameter name="hostname"&gt;10.0.0.5&lt;/parameter&gt;</div>
</td>
<td>No</td>
<td>localhost</td>
</tr>
<tr>
<td>httpGetProcessor</td>
<td>
The full qualified name of the class that's responsible for handling incoming
HTTP GET requests. The specified class must implement the
org.apache.synapse.transport.passthru.HttpGetRequestProcessor interface. If it
is required to customize the way Synapse handles HTTP GET requests, one could
implement the above interface, and register the custom class with Synapse using
this parameter. By default Synapse ships with an HTTP GET request handler that
responds to ?wsdl and ?xsd requests and mediates all the others.
<div class="xmlConf">&lt;parameter name="httpGetProcessor"&gt;foo.bar.CustomGETProcessor&lt;/parameter&gt;</div>
</td>
<td>No</td>
<td>N/A</td>
</tr>
<tr>
<td>WSDLEPRPrefix</td>
<td>
A URL prefix that should be added to all the HTTP endpoints exposed
through this transport listener. This prefix will appear in all WSDLs
advertised by the transport. This is particularly useful when Synapse
is fronted by a proxy server or a load balancer and it is required to mention
the proxy/load balancer endpoints in the WSDLs generated by Synapse. This
parameter has higher priority than the hostname parameter.
<div class="xmlConf">&lt;parameter name="WSDLEPRPrefix"&gt;http://proxy.example.com:8080/&lt;/parameter&gt;</div>
</td>
<td>No</td>
<td>http://&lt;host&gt;:&lt;port&gt;/</td>
</tr>
</table>
<p>
All the above parameters are also applicable to the HTTPS transport listener.
</p>
</subsection>
<subsection name="HTTP Transport Sender" id="HTTPSender">
<p>
The default Pass Through HTTP sender configuration available in the axis2.xml
file is shown below.
</p>
<div class="xmlConf">&lt;transportSender name="http" class="org.apache.synapse.transport.passthru.PassThroughHttpSender" /&gt;</div>
<p>
Following parameters can be specified to customize the behavior of the HTTP
sender.
</p>
<table>
<tr>
<th>Parameter Name</th>
<th>Description/Example</th>
<th>Required</th>
<th>Default</th>
</tr>
<tr>
<td>http.proxyHost</td>
<td>
The hostname or IP address of the proxy server through which the HTTP
messages should be sent. Use this property when Synapse should use an
external HTTP proxy to tunnel the outgoing HTTP traffic. This parameter
is only applicable to the HTTP sender. HTTPS sender does not support
external proxies yet.
<div class="xmlConf">&lt;parameter name="http.proxyHost"&gt;proxy.example.com&lt;/parameter&gt;</div>
</td>
<td>No</td>
<td>N/A</td>
</tr>
<tr>
<td>http.proxyPort</td>
<td>
The port number of the proxy server through which the HTTP messages
should be sent. Only used if the http.proxyHost parameter is also
configured. This parameter is only applicable to the HTTP sender.
HTTPS sender does not support external proxies yet.
<div class="xmlConf">&lt;parameter name="http.proxyPort"&gt;8080&lt;/parameter&gt;</div>
</td>
<td>No</td>
<td>80</td>
</tr>
<tr>
<td>http.nonProxyHosts</td>
<td>
Use this parameter to specify a proxy bypass list. That is, a list of
target hosts for which Synapse will not use the configured external
proxy. Only used if the http.proxyHost parameter is also set. The value
of this parameter can be a single hostname/IP address or a list of
hostnames/IP addresses separated by the '|' character. Parameter also
supports regular expressions which can be used to specify hostname
patterns.
<div class="xmlConf">&lt;parameter name="http.nonProxyHosts"&gt;10.0.0.8|foo.com|*.bar.org&lt;/parameter&gt;</div>
</td>
<td>No</td>
<td>N/A</td>
</tr>
</table>
</subsection>
<subsection name="HTTPS Transport Listener" id="HTTPSListener">
<p>
Pass Through HTTPS listener supports all the parameters supported by the
HTTP listener. In addition, HTTPS listener supports several SSL/TLS specific
parameters. The default HTTPS listener configuration in the axis2.xml file is
shown below.
</p>
<div class="xmlConf">&lt;transportReceiver name="https" class="org.apache.synapse.transport.passthru.PassThroughHttpSSLListener"&gt;
&lt;parameter name="port" locked="false"&gt;8243&lt;/parameter&gt;
&lt;parameter name="httpGetProcessor" locked="false"&gt;org.apache.synapse.transport.passthru.api.PassThroughNHttpGetProcessor&lt;/parameter&gt;
&lt;parameter name="keystore" locked="false"&gt;
&lt;KeyStore&gt;
&lt;Location&gt;lib/identity.jks&lt;/Location&gt;
&lt;Type&gt;JKS&lt;/Type&gt;
&lt;Password&gt;password&lt;/Password&gt;
&lt;KeyPassword&gt;password&lt;/KeyPassword&gt;
&lt;/KeyStore&gt;
&lt;/parameter&gt;
&lt;parameter name="truststore" locked="false"&gt;
&lt;TrustStore&gt;
&lt;Location&gt;lib/trust.jks&lt;/Location&gt;
&lt;Type&gt;JKS&lt;/Type&gt;
&lt;Password&gt;password&lt;/Password&gt;
&lt;/TrustStore&gt;
&lt;/parameter&gt;
&lt;/transportReceiver&gt;</div>
<p>
A complete list of parameters supported by the HTTPS listener is given below.
Information regarding the parameters also supported by the HTTP listener are
duplicated here for reader's convenience.
</p>
<table>
<tr>
<th>Parameter Name</th>
<th>Description/Example</th>
<th>Required</th>
<th>Default</th>
</tr>
<tr>
<td>port</td>
<td>
The port number on which the HTTP listener should listen.
<div class="xmlConf">&lt;parameter name="port"&gt;8280&lt;/parameter&gt;</div>
</td>
<td>Yes</td>
<td>N/A</td>
</tr>
<tr>
<td>keystore</td>
<td>
Specifies the keystore that should be used to initialize SSL/TLS
support. A keystore typically houses a private key and some certificates
with their corresponding public keys. The value of this parameter is a
complex XML element. This XML element should specify:
<ul>
<li>Location: Path to the keystore file</li>
<li>Type: type of the keystore file (JKS, PKCS etc.)</li>
<li>Password: Password to unlock the keystore file</li>
<li>KeyPassword: Password to unlock the private key in the keystore file</li>
</ul>
All 4 values are required. Keystore paths are resolved relative to the
Synapse installation (SYNAPSE_HOME) directory. If you are not familiar with
Java security and keystores, please refer
<a href="http://docs.oracle.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html">Java Cryptography Architecture</a>
specification.
<br/>
<br/>
<strong>
Synapse ships with a default keystore file. It is highly recommended
that a different keystore file is used in production deployments of
Synapse, since the passwords of the default keystore are publicly
known.
</strong>
<div class="xmlConf">&lt;parameter name="keystore" locked="false"&gt;
&lt;KeyStore&gt;
&lt;Location&gt;lib/identity.jks&lt;/Location&gt;
&lt;Type&gt;JKS&lt;/Type&gt;
&lt;Password&gt;password&lt;/Password&gt;
&lt;KeyPassword&gt;password&lt;/KeyPassword&gt;
&lt;/KeyStore&gt;
&lt;/parameter&gt;</div>
</td>
<td>No</td>
<td>N/A</td>
</tr>
<tr>
<td>truststore</td>
<td>
Specifies the truststore that should be used to initialize SSL/TLS
support. A truststore typically houses the CA certificates and other
trusted public certificates. The value of this parameter is a complex
XML element. This XML element should specify:
<ul>
<li>Location: Path to the truststore file</li>
<li>Type: type of the truststore file (JKS, PKCS etc.)</li>
<li>Password: Password to unlock the truststore file</li>
</ul>
All 3 values are required. Truststore paths are resolved relative to the
Synapse installation (SYNAPSE_HOME) directory. If you are not familiar with
Java security and truststores, please refer
<a href="http://docs.oracle.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html">Java Cryptography Architecture</a>
specification.
<br/>
<br/>
<strong>
Synapse ships with a default truststore file. It is highly recommended
that a different truststore file is used in production deployments of
Synapse, since the password of the default truststore is publicly
known.
</strong>
<div class="xmlConf">&lt;parameter name="truststore" locked="false"&gt;
&lt;TrustStore&gt;
&lt;Location&gt;lib/trust.jks&lt;/Location&gt;
&lt;Type&gt;JKS&lt;/Type&gt;
&lt;Password&gt;password&lt;/Password&gt;
&lt;/TrustStore&gt;
&lt;/parameter&gt;</div>
</td>
<td>No</td>
<td>N/A</td>
</tr>
<tr>
<td>SSLVerifyClient</td>
<td>
Use this parameter to enable client certificate verification (client
authentication). This option provides functionality similar to the
<a href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslverifyclient">SSLVerifyClient directive</a>
of Apache HTTPD. Supported values are:
<ul>
<li>none: No client certificate is required</li>
<li>optional: Client may present a valid certificate, but is not required to do so</li>
<li>require: Client must present a valid certificate (the SSL handshake will not succeed without it)</li>
</ul>
<div class="xmlConf">&lt;parameter name="SSLVerifyClient"&gt;require&lt;/parameter&gt;</div>
</td>
<td>No</td>
<td>None</td>
</tr>
<tr>
<td>bind-address</td>
<td>
The hostname or IP address to which the HTTP listener should bind. When
deploying Synapse on machines that have multiple network interfaces,
this parameter can be used to bind the HTTP listener to a specific network
interface.
<div class="xmlConf">&lt;parameter name="bind-address"&gt;10.0.0.5&lt;/parameter&gt;</div>
</td>
<td>No</td>
<td>All available network interfaces</td>
</tr>
<tr>
<td>hostname</td>
<td>
The hostname or IP address used to calculate the service endpoints
exposed through this transport listener. This can be used to customize
the hostname of the endpoints (EPRs) that appear in the generated WSDLs.
This parameter is ignored if the WSDLEPRPrefix parameter is set.
<div class="xmlConf">&lt;parameter name="hostname"&gt;10.0.0.5&lt;/parameter&gt;</div>
</td>
<td>No</td>
<td>localhost</td>
</tr>
<tr>
<td>httpGetProcessor</td>
<td>
The full qualified name of the class that's responsible for handling incoming
HTTP GET requests. The specified class must implement the
org.apache.synapse.transport.passthru.HttpGetRequestProcessor interface. If it
is required to customize the way Synapse handles HTTP GET requests, one could
implement the above interface, and register the custom class with Synapse using
this parameter. By default Synapse ships with an HTTP GET request handler that
responds to ?wsdl and ?xsd requests and mediates all the others.
<div class="xmlConf">&lt;parameter name="httpGetProcessor"&gt;foo.bar.CustomGETProcessor&lt;/parameter&gt;</div>
</td>
<td>No</td>
<td>N/A</td>
</tr>
<tr>
<td>WSDLEPRPrefix</td>
<td>
A URL prefix that should be added to all the HTTP endpoints exposed
through this transport listener. This prefix will appear in all WSDLs
advertised by the transport. This is particularly useful when Synapse
is fronted by a proxy server or a load balancer and it is required to mention
the proxy/load balancer endpoints in the WSDLs generated by Synapse. This
parameter has higher priority than the hostname parameter.
<div class="xmlConf">&lt;parameter name="WSDLEPRPrefix"&gt;https://proxy.example.com:8443/&lt;/parameter&gt;</div>
</td>
<td>No</td>
<td>https://&lt;host&gt;:&lt;port&gt;/</td>
</tr>
</table>
</subsection>
<subsection name="HTTPS Transport Sender" id="HTTPSSender">
<p>
As of today, the Pass Through HTTPS sender does not support sending messages
through an external proxy. Therefore some of the parameters supported by the
HTTP sender (http.proxyHost, http.proxyPort etc.) cannot be used with the
HTTPS sender. However, there are several SSL/TLS related parameters that need
to be configured when setting up the HTTPS sender. The default HTTPS sender
configuration in the axis2.xml file is shown below.
</p>
<div class="xmlConf">&lt;transportSender name="https" class="org.apache.synapse.transport.passthru.PassThroughHttpSSLSender"&gt;
&lt;parameter name="keystore" locked="false"&gt;
&lt;KeyStore&gt;
&lt;Location&gt;lib/identity.jks&lt;/Location&gt;
&lt;Type&gt;JKS&lt;/Type&gt;
&lt;Password&gt;password&lt;/Password&gt;
&lt;KeyPassword&gt;password&lt;/KeyPassword&gt;
&lt;/KeyStore&gt;
&lt;/parameter&gt;
&lt;parameter name="truststore" locked="false"&gt;
&lt;TrustStore&gt;
&lt;Location&gt;lib/trust.jks&lt;/Location&gt;
&lt;Type&gt;JKS&lt;/Type&gt;
&lt;Password&gt;password&lt;/Password&gt;
&lt;/TrustStore&gt;
&lt;/parameter&gt;
&lt;/transportSender&gt;</div>
<p>
Following table lists all the parameters supported by the Pass Through HTTPS
sender.
</p>
<table>
<tr>
<th>Parameter Name</th>
<th>Description/Example</th>
<th>Required</th>
<th>Default</th>
</tr>
<tr>
<td>keystore</td>
<td>
Specifies the keystore that should be used to initialize SSL/TLS
support. A keystore typically houses a private key and some certificates
with their corresponding public keys. The value of this parameter is a
complex XML element. This XML element should specify:
<ul>
<li>Location: Path to the keystore file</li>
<li>Type: type of the keystore file (JKS, PKCS etc.)</li>
<li>Password: Password to unlock the keystore file</li>
<li>KeyPassword: Password to unlock the private key in the keystore file</li>
</ul>
All 4 values are required. Keystore paths are resolved relative to the
Synapse installation (SYNAPSE_HOME) directory. If you are not familiar with
Java security and keystores, please refer
<a href="http://docs.oracle.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html">Java Cryptography Architecture</a>
specification.
<br/>
<br/>
<strong>
Synapse ships with a default keystore file. It is highly recommended
that a different keystore file is used in production deployments of
Synapse, since the passwords of the default keystore are publicly
known.
</strong>
<div class="xmlConf">&lt;parameter name="keystore" locked="false"&gt;
&lt;KeyStore&gt;
&lt;Location&gt;lib/identity.jks&lt;/Location&gt;
&lt;Type&gt;JKS&lt;/Type&gt;
&lt;Password&gt;password&lt;/Password&gt;
&lt;KeyPassword&gt;password&lt;/KeyPassword&gt;
&lt;/KeyStore&gt;
&lt;/parameter&gt;</div>
</td>
<td>No</td>
<td>N/A</td>
</tr>
<tr>
<td>truststore</td>
<td>
Specifies the truststore that should be used to initialize SSL/TLS
support. A truststore typically houses the CA certificates and other
trusted public certificates. The value of this parameter is a complex
XML element. This XML element should specify:
<ul>
<li>Location: Path to the truststore file</li>
<li>Type: type of the truststore file (JKS, PKCS etc.)</li>
<li>Password: Password to unlock the truststore file</li>
</ul>
All 3 values are required. Truststore paths are resolved relative to the
Synapse installation (SYNAPSE_HOME) directory. If you are not familiar with
Java security and truststores, please refer
<a href="http://docs.oracle.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html">Java Cryptography Architecture</a>
specification.
<br/>
<br/>
<strong>
Synapse ships with a default truststore file. It is highly recommended
that a different truststore file is used in production deployments of
Synapse, since the password of the default truststore is publicly
known.
</strong>
<div class="xmlConf">&lt;parameter name="truststore" locked="false"&gt;
&lt;TrustStore&gt;
&lt;Location&gt;lib/trust.jks&lt;/Location&gt;
&lt;Type&gt;JKS&lt;/Type&gt;
&lt;Password&gt;password&lt;/Password&gt;
&lt;/TrustStore&gt;
&lt;/parameter&gt;</div>
</td>
<td>No</td>
<td>N/A</td>
</tr>
<tr>
<td>HostnameVerifier</td>
<td>
This parameter can be used to configure target hostname verification.
That is, it enables validating server hostnames against the names specified
in the certificates presented by the servers during SSL handshake.
Supported values are:
<ul>
<li>Default</li>
<li>DefaultAndLocalhost</li>
<li>AllowAll</li>
<li>Strict</li>
</ul>
Please refer <a href="http://synapse.apache.org/apidocs/org/apache/synapse/transport/nhttp/HostnameVerifier.html">HostnameVerifier</a>
Javadocs to learn more about this feature and the semantics of the above
options. The AllowAll option essentially disables hostname verification
by accepting all certificates. The Strict option requires the server
hostnames to match exactly to the names specified in the server certificates.
Any deviations will cause the SSL handshake to fail.
<div class="xmlConf">&lt;parameter name="HostnameVerifier"&gt;Strict&lt;/parameter&gt;</div>
</td>
<td>No</td>
<td>Default</td>
</tr>
<tr>
<td>novalidatecert</td>
<td>
Use this parameter to turn on/off server certificate validation. If set to
'true', the HTTPS sender will not attempt to validate the certificates
presented by the remote servers. This behavior, however, is not recommended
for production deployments due to the potential security risks. If the
truststore parameter is specified, the value of this parameter is ignored
altogether.
<div class="xmlConf">&lt;parameter name="novalidatecert"&gt;true&lt;/parameter&gt;</div>
</td>
<td>No</td>
<td>false</td>
</tr>
<tr>
<td>customSSLProfiles</td>
<td>
By default, the HTTPS sender uses the SSL settings configured under
keystore and truststore parameters to communicate with all remote
HTTPS endpoints. However, in some cases we may need to use different
SSL settings to communicate with different endpoints. The customSSLProfiles
parameter allows configuring separate keystores and truststores for
each destination server. The value of this parameter is a set of XML elements
(profile elements). Each profile element must be configured with the following
child elements:
<ul>
<li>servers: A comma-separated list of servers to which this SSL profile is related to</li>
<li>KeyStore: A keystore configuration (similar to the keystore parameter)</li>
<li>TrustStore: A truststore configuration (similar to the truststore parameter)</li>
<li>novalidatecert: Optional element to disable certification validation (can be set to true or false)</li>
</ul>
An example is given below. According to this configuration, when Synapse
communicates with server1.example.com or server2.example.com, it will use
the first SSL configuration (identity1.jks and trust1.jks). When
communicating with server3.example.com, it will use the second SSL
configuration (identity2.jks and trust2.jks). For all other endpoints,
Synapse will use the default SSL configuration, configured under keystore
and truststore parameters.
<div class="xmlConf">&lt;parameter name="customSSLProfiles"&gt;
&lt;profile&gt;
&lt;servers&gt;server1.example.com:443,server2.example.com:443&lt;/servers&gt;
&lt;KeyStore&gt;
&lt;Location&gt;lib/identity1.jks&lt;/Location&gt;
&lt;Type&gt;JKS&lt;/Type&gt;
&lt;Password&gt;password&lt;/Password&gt;
&lt;KeyPassword&gt;password&lt;/KeyPassword&gt;
&lt;/KeyStore&gt;
&lt;TrustStore&gt;
&lt;Location&gt;lib/trust1.jks&lt;/Location&gt;
&lt;Type&gt;JKS&lt;/Type&gt;
&lt;Password&gt;password&lt;/Password&gt;
&lt;/TrustStore&gt;
&lt;/profile&gt;
&lt;profile&gt;
&lt;servers&gt;server3.example.com:443&lt;/servers&gt;
&lt;KeyStore&gt;
&lt;Location&gt;lib/identity2.jks&lt;/Location&gt;
&lt;Type&gt;JKS&lt;/Type&gt;
&lt;Password&gt;password&lt;/Password&gt;
&lt;KeyPassword&gt;password&lt;/KeyPassword&gt;
&lt;/KeyStore&gt;
&lt;TrustStore&gt;
&lt;Location&gt;lib/trust2.jks&lt;/Location&gt;
&lt;Type&gt;JKS&lt;/Type&gt;
&lt;Password&gt;password&lt;/Password&gt;
&lt;/TrustStore&gt;
&lt;/profile&gt;
&lt;/parameter&gt;</div>
</td>
<td>No</td>
<td>N/A</td>
</tr>
<tr>
<td>CertificateRevocationVerifier</td>
<td>
Enable revocation status validation of server certificates using
<a href="http://www.ietf.org/rfc/rfc2560.txt">OCSP</a> and
<a href="http://www.ietf.org/rfc/rfc5280.txt">CRL</a>. Simply uncommenting
this parameter under the HTTPS sender configuration will activate the
feature. Two LRU caches are used to cache CRLs and OCSP responses until
they are expired. Two child XML elements are used to configure the cache
behavior.
<ul>
<li>
CacheSize: Controls the maximum size of each cache. When this
limit is reached, the old values will be automatically removed
and updated with new values. Default value is 50.
</li>
<li>
CacheDurationMins: Set the time duration (in minutes) between
two consecutive runs of the CacheManager task which periodically
performs housekeeping work in each cache. Default value is 15.
</li>
</ul>
<div class="xmlConf">&lt;parameter name="CertificateRevocationVerifier" locked="false"&gt;
&lt;CacheSize&gt;100&lt;/CacheSize&gt;
&lt;CacheDurationMins&gt;&lt;/CacheDurationMins&gt;
&lt;/parameter&gt;</div>
</td>
<td>No</td>
<td>N/A</td>
</tr>
</table>
</subsection>
</section>
<section name="Advanced Settings and Performance Tuning" id="AdvancedSettings">
<p>
In addition to the basic parameters described in the previous section, the
Pass Through HTTP transport provides some advanced options to tweak its
runtime behavior and performance. These options are configured in the
passthru-http.properties file which should be placed in the lib directory of
Synapse. These advanced options enable the user to control some of the low-level
transport settings related to TCP sockets, I/O buffers and thread pools. Following
table describes all the advanced options that can be set for the Pass Through
HTTP transport.
</p>
<table>
<tr>
<th>Parameter Name</th>
<th>Description/Example</th>
<th>Required</th>
<th>Default</th>
</tr>
<tr>
<td>http.socket.timeout</td>
<td>
Set the TCP socket timeout in milliseconds
(See <a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/net/SocketOptions.html#SO_TIMEOUT">SO_TIMEOUT</a>).
<div class="xmlConf">http.socket.timeout=20000</div>
</td>
<td>No</td>
<td>60000</td>
</tr>
<tr>
<td>http.connection.timeout</td>
<td>
Set the TCP connection timeout in milliseconds. This determines the timeout
value for non-blocking connection requests. Setting this property to
0 disables connection timeout (i.e. no timeout).
<div class="xmlConf">http.connection.timeout=30000</div>
</td>
<td>No</td>
<td>0</td>
</tr>
<tr>
<td>http.nio.interest-ops-queueing</td>
<td>
Determines whether or not I/O interest operations are to be queued and
executed asynchronously by the I/O reactor thread or to be applied to
the underlying
<a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/nio/channels/SelectionKey.html">SelectionKey</a>
immediately. Allowed values are either 'true' or 'false'.
<div class="xmlConf">http.nio.interest-ops-queueing=false</div>
</td>
<td>No</td>
<td>false</td>
</tr>
<tr>
<td>http.tcp.nodelay</td>
<td>
Setting this property to 'true' disables
<a href="http://en.wikipedia.org/wiki/Nagle's_algorithm">Nagle's algorithm</a>
for the HTTP connections. That is, outgoing data will not be buffered
and aggregated together
(See <a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/net/SocketOptions.html#TCP_NODELAY">TCP_NODELAY</a>).
<div class="xmlConf">http.tcp.nodelay=true</div>
</td>
<td>No</td>
<td>true</td>
</tr>
<tr>
<td>http.socket.rcv-buffer-size</td>
<td>
Set the size of the buffers used by the underlying platform
for incoming network I/O. This value is only a hint. When set, this is a
suggestion to the OS kernel from Synapse about the size of buffers to
use for the data to be received over the socket
(See <a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/net/SocketOptions.html#SO_RCVBUF">SO_RCVBUF</a>).
<div class="xmlConf">http.socket.rcv-buffer-size=4096</div>
</td>
<td>No</td>
<td>8192</td>
</tr>
<tr>
<td>http.socket.snd-buffer-size</td>
<td>
Set the size of the buffers used by the underlying platform
for outgoing network I/O. This value is only a hint. When set, this is a
suggestion to the OS kernel from Synapse about the size of buffers to
use for the data to be sent over the socket
(See <a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/net/SocketOptions.html#SO_SNDBUF">SO_SNDBUF</a>).
<div class="xmlConf">http.socket.snd-buffer-size=4096</div>
</td>
<td>No</td>
<td>8192</td>
</tr>
<tr>
<td>http.socket.linger</td>
<td>
Specify the linger-on-close timeout duration (in milliseconds) for the
sockets created by the HTTP transport. Setting to 0 or a negative value
disables linger-on-close
(See <a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/net/SocketOptions.html#SO_LINGER">SO_LINGER</a>).
<div class="xmlConf">http.socket.linger=5000</div>
</td>
<td>No</td>
<td>-1</td>
</tr>
<tr>
<td>http.socket.reuseaddr</td>
<td>
Set the <a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/net/SocketOptions.html#SO_REUSEADDR">SO_REUSEADDR</a>
socket option for the sockets created by the HTTP transport. Accepted
values are either 'true' or 'false'.
<div class="xmlConf">http.socket.reuseaddr=true</div>
</td>
<td>No</td>
<td>false</td>
</tr>
<tr>
<td>http.nio.select-interval</td>
<td>
Set the time interval in milliseconds at which the I/O reactor wakes up
to check for timed out sessions and session requests.
<div class="xmlConf">http.nio.select-interval=2500</div>
</td>
<td>No</td>
<td>1000</td>
</tr>
<tr>
<td>io_threads_per_reactor</td>
<td>
Set the number of I/O dispatcher threads to be used by each I/O reactor.
Typically, this property controls the ability of the HTTP transport
to handle concurrent I/O events.
It is recommended that this property is set to the number of CPU cores
available for Synapse. By default, Synapse determines the number of
available CPU cores and initializes this setting accordingly.
<div class="xmlConf">io_threads_per_reactor=4</div>
</td>
<td>No</td>
<td>Number of CPU cores</td>
</tr>
<tr>
<td>http.malformed.input.action</td>
<td>
Specify the action to be performed when a malformed input is detected
during character set encoding or decoding. Supported values are
'ignore', 'replace' and 'report'. See <a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/nio/charset/CodingErrorAction.html">CodingErrorAction</a>
for more details on each of these options.
<div class="xmlConf">http.malformed.input.action=ignore</div>
</td>
<td>No</td>
<td>report</td>
</tr>
<tr>
<td>http.unmappable.input.action</td>
<td>
Specify the action to be performed when an un-mappable character is detected
during character set encoding or decoding. Supported values are
'ignore', 'replace' and 'report'. See <a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/nio/charset/CodingErrorAction.html">CodingErrorAction</a>
for more details on each of these options.
<div class="xmlConf">http.malformed.input.action=ignore</div>
</td>
<td>No</td>
<td>report</td>
</tr>
<tr>
<td>worker_pool_size_core</td>
<td>
Initial size of the internal thread pool used by the Pass
Through HTTP transport. This thread pool is used for mediating
messages through the Synapse mediation engine. Note that both HTTP
listener and sender draw threads from this pool. It is further shared
between the HTTP and HTTPS transports. The size of this thread pool
determines the capacity of Synapse to mediate concurrent HTTP messages.
<div class="xmlConf">worker_pool_size_core=100</div>
</td>
<td>No</td>
<td>40</td>
</tr>
<tr>
<td>worker_pool_size_max</td>
<td>
The thread pool used by the Pass Through HTTP transport grows in size, as
more and more jobs are submitted to it. This property determines the
maximum limit up to which the thread pool may grow. In other words,
this property specifies the maximum number of threads that may ever exist
in the transport thread pool. Value of this property must be greater than
or equal to the vallue of worker_pool_size_core.
<div class="xmlConf">worker_pool_size_max=500</div>
</td>
<td>No</td>
<td>200</td>
</tr>
<tr>
<td>worker_thread_keepalive_sec</td>
<td>
Specify the idle time period (in seconds) for the excessive threads in
the Pass Through transport thread pool. Once a thread in the pool has
been idle for this duration, it will be removed from the pool and
destroyed. This reduces the size of the thread pool, but the thread pool
size is not to allowed drop below the value of the worker_pool_size_core
property.
<div class="xmlConf">worker_thread_keepalive_sec=10</div>
</td>
<td>No</td>
<td>60</td>
</tr>
<tr>
<td>worker_pool_queue_length</td>
<td>
Determines the length of the queue used by the Pass Through transport
thread pool to store pending jobs. To use an unbounded queue, set this
property to -1. If a bounded queue is used, and if the queue ever gets
filled to its capacity, any further attempts to submit jobs will fail,
causing some messages to be dropped by Synapse.
<div class="xmlConf">worker_pool_queue_length=1000</div>
</td>
<td>No</td>
<td>-1</td>
</tr>
</table>
<p>
Note that all the above settings are optional. In fact the entire passthru-http.properties
file is optional. Synapse is programmed with some reasonable default values (also
given in the table) for each of the above settings. However, it is highly
recommended to tweak the above values to obtain best performance from the
Pass Through HTTP transport. At least, consider tuning the worker_pool_size_core
and worker_pool_size_max to match the expected load in your deployment.
</p>
<subsection name="Unix/Linux Specific Settings" id="LinuxSettings">
<p>
Users deploying Synapse on Unix/Linux systems are further advised to set the
following OS level configuration parameters. This is completely optional, but
for high-throughput and high-volume deployments, configuring these parameters
may be crucial.
</p>
<ul>
<li>
Increase the limit on open file descriptors by editing the
/etc/security/limits.conf file.
<div class="xmlConf">* soft nofile 4096
* hard nofile 65535</div>
</li>
<li>
Increase the TCP port range and optimize other TCP settings in the
/etc/sysctl.conf file.
<div class="xmlConf">net.ipv4.tcp_fin_timeout = 30
fs.file-max = 2097152
net.ipv4.tcp_tw_recycle = 1
net.ipv4.tcp_tw_reuse = 1
net.core.rmem_default = 524288
net.core.wmem_default = 524288
net.core.rmem_max = 67108864
net.core.wmem_max = 67108864
net.ipv4.tcp_rmem = 4096 87380 16777216
net.ipv4.tcp_wmem = 4096 65536 16777216
net.ipv4.ip_local_port_range = 1024 65535</div>
</li>
</ul>
</subsection>
</section>
<section name="Logging Configuration" id="Logging">
<p>
<strong>Note: This section is applicable to both Pass Through and NHTTP transports of
Synapse.</strong>
</p>
<p>
Synapse HTTP transports have some advanced logging capabilities built in to them,
which can be enabled to obtain more low-level information about how the transports
operate. These logging features are based on
<a href="http://commons.apache.org/proper/commons-logging/">Apache Commons Logging</a>
and Log4J, which constitute the logging framework used by Apache Synapse. Therefore,
these features should be enabled from the log4j.properties file, which can be found
in the lib directory of the Synapse installation.
</p>
<p>
Advanced logging for HTTP transports is activated by setting the log level to DEBUG
on a set of predefined logging categories. These categories are already listed in
the default log4j.properties file that ships with Synapse, and you only need to
uncomment them to use the advanced logging features. Please note that changes to
log4j.properties file are not picked up at runtime, and therefore you must restart
Synapse for the changes to take effect. A complete listing of the logging categories
related to Synapse HTTP transports is given below.
</p>
<dl>
<dt>
<tt>log4j.category.org.apache.synapse.transport.http.headers=DEBUG</tt>
</dt>
<dd>
Enables logging the headers of all the HTTP messages received and sent by
Synapse.
</dd>
<dt>
<tt>log4j.category.org.apache.synapse.transport.http.headers.SourceHeaders=DEBUG</tt>
</dt>
<dd>
Enables logging the headers of all the HTTP messages exchanged between client
applications and Synapse.
</dd>
<dt>
<tt>log4j.category.org.apache.synapse.transport.http.headers.TargetHeaders=DEBUG</tt>
</dt>
<dd>
Enables logging the headers of all the HTTP messages exchanged between Synapse
and backend servers.
</dd>
</dl>
<dl>
<dt>
<tt>log4j.category.org.apache.synapse.transport.http.wire=DEBUG</tt>
</dt>
<dd>
Enables logging the complete wire-level messages received and sent by Synapse.
This will log HTTP headers as well message bodies.
</dd>
<dt>
<tt>log4j.category.org.apache.synapse.transport.http.wire.SourceWire=DEBUG</tt>
</dt>
<dd>
Enables logging the complete wire-level messages exchanged between client
applications and Synapse.
</dd>
<dt>
<tt>log4j.category.org.apache.synapse.transport.http.wire.TargetWire=DEBUG</tt>
</dt>
<dd>
Enables logging the complete wire-level messages exchanged between Synapse
and backend servers.
</dd>
</dl>
<dl>
<dt>
<tt>log4j.category.org.apache.synapse.transport.http.conn=DEBUG</tt>
</dt>
<dd>
Enables logging for all HTTP connections. This will log all the significant events
that occur on HTTP connections during their life cycles. Some of these events
include read, write and shutdown.
</dd>
<dt>
<tt>log4j.category.org.apache.synapse.transport.http.conn.SourceConnection=DEBUG</tt>
</dt>
<dd>
Enables logging for HTTP connections established between client applications and
Synapse.
</dd>
<dt>
<tt>log4j.category.org.apache.synapse.transport.http.conn.TargetConnection=DEBUG</tt>
</dt>
<dd>
Enables logging for HTTP connections established between Synapse and backend
servers.
</dd>
</dl>
<dl>
<dt>
<tt>log4j.category.org.apache.synapse.transport.http.session=DEBUG</tt>
</dt>
<dd>
Enables logging for all I/O sessions. This will log all the significant events
that occur on HTTP I/O sessions during their life cycles. Some of these events
include setting NIO interest ops, read, write and shutdown.
</dd>
<dt>
<tt>log4j.category.org.apache.synapse.transport.http.session.SourceSession=DEBUG</tt>
</dt>
<dd>
Enables logging for I/O sessions established between client applications and
Synapse.
</dd>
<dt>
<tt>log4j.category.org.apache.synapse.transport.http.session.TargetSession=DEBUG</tt>
</dt>
<dd>
Enables logging for I/O sessions established between Synapse and backend
servers.
</dd>
</dl>
<dl>
<dt>
<tt>log4j.category.org.apache.synapse.transport.http=DEBUG</tt>
</dt>
<dd>
Enables all the advanced logging features (all listed above).
</dd>
</dl>
<subsection name="Guidelines for Using Advanced Logging" id="LoggingGuidelines">
<p>
Most of the above advanced logging features have been designed to aid Synapse developers
in identifying problems and fixing issues in the Synapse HTTP transports. However,
they are also useful to the Synapse users and system administrators when debugging
configuration errors and certain types of integration problems. For instance, if you
ever come across a situation where Synapse behaves erratically when communicating
with a particular client or a server, enabling some of the above mentioned logging
features may help you pinpoint the cause of the issue.
</p>
<p>
Please bare in mind that you trade mediation performance for additional logging.
As you enable more and more logging features, the performance degradation induced
by logging becomes greater. Hence these advanced logging features are not suitable
to be enabled on production deployments. However, they are quite helpful during the
development and testing phases of an integration project. In a production deployment,
you may occasionally need to enable advanced logging for short periods of time to obtain
debug information to resolve certain production issues. But it is not recommended to
have these features permanently enabled on production systems.
</p>
<p>
Also note that activating advanced logging features may greatly increase the amount
of data written to the Synapse log files. If the Synapse server is receiving a large
volume of traffic, enabling any one of the above logging features may cause
Synapse to generate gigabytes of logs within minutes. This could easily drive a
system out of disk space or cause some other unexpected I/O issue. Therefore be
mindful about how much extra information you want Synapse to log, the prevailing
levels of load/traffic and the availability of hardware resources.
</p>
</subsection>
</section>
</body>
</document>