synapse-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From va...@apache.org
Subject svn commit: r1817077 [33/34] - in /synapse/site/3_0_1: ./ css/ dev/ fonts/ images/ images/logos/ images/profiles/ img/ js/ userguide/ userguide/samples/ userguide/samples/setup/ userguide/transports/
Date Mon, 04 Dec 2017 09:54:01 GMT
Added: synapse/site/3_0_1/userguide/transports/pass_through.html
URL: http://svn.apache.org/viewvc/synapse/site/3_0_1/userguide/transports/pass_through.html?rev=1817077&view=auto
==============================================================================
--- synapse/site/3_0_1/userguide/transports/pass_through.html (added)
+++ synapse/site/3_0_1/userguide/transports/pass_through.html Mon Dec  4 09:53:57 2017
@@ -0,0 +1,2491 @@
+<!DOCTYPE html>
+<!--
+ | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2017-12-04 
+ | Rendered using Apache Maven Fluido Skin 1.6
+-->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="Date-Revision-yyyymmdd" content="20171204" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>Apache Synapse &#x2013; Apache Synapse - Pass Through HTTP Transport</title>
+    <link rel="stylesheet" href="../../css/apache-maven-fluido-1.6.min.css" />
+    <link rel="stylesheet" href="../../css/site.css" />
+    <link rel="stylesheet" href="../../css/print.css" media="print" />
+      <script type="text/javascript" src="../../js/apache-maven-fluido-1.6.min.js"></script>
+      </head>
+    <body class="topBarDisabled">
+      <div class="container-fluid">
+      <div id="banner">
+        <div class="pull-left"><div id="bannerLeft"><h2>Apache Synapse</h2>
+</div>
+</div>
+        <div class="pull-right"></div>
+        <div class="clear"><hr/></div>
+      </div>
+
+      <div id="breadcrumbs">
+        <ul class="breadcrumb">
+        <li id="publishDate">Last Published: 2017-12-04<span class="divider">|</span>
+</li>
+          <li id="projectVersion">Version: 3.0.1</li>
+        </ul>
+      </div>
+      <div class="row-fluid">
+        <div id="leftColumn" class="span2">
+          <div class="well sidebar-nav">
+<ul class="nav nav-list">
+          <li class="nav-header">Main Menu</li>
+    <li><a href="../../index.html" title="Home"><span class="none"></span>Home</a>  </li>
+    <li><a href="../../download.html" title="Download"><span class="none"></span>Download</a>  </li>
+    <li><a href="../../history.html" title="History"><span class="none"></span>History</a>  </li>
+    <li><a href="http://www.apache.org/licenses/LICENSE-2.0" class="externalLink" title="License"><span class="none"></span>License</a>  </li>
+    <li><a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks"><span class="none"></span>Thanks</a>  </li>
+    <li><a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship"><span class="none"></span>Sponsorship</a>  </li>
+    <li><a href="http://www.apache.org/security/" class="externalLink" title="Security"><span class="none"></span>Security</a>  </li>
+          <li class="nav-header">Documentation</li>
+    <li><a href="../../userguide/installation.html" title="Installation Guide"><span class="none"></span>Installation Guide</a>  </li>
+    <li><a href="../../userguide/quick_start.html" title="Quick Start Guide"><span class="none"></span>Quick Start Guide</a>  </li>
+    <li><a href="../../userguide/samples/setup/index.html" title="Samples Setup Guide"><span class="none"></span>Samples Setup Guide</a>  </li>
+    <li><a href="../../userguide/samples.html" title="Samples Catalog"><span class="none"></span>Samples Catalog</a>  </li>
+    <li><a href="../../userguide/config.html" title="Configuration Language"><span class="none"></span>Configuration Language</a>  </li>
+    <li><a href="../../userguide/mediators.html" title="Mediators Catalog"><span class="none"></span>Mediators Catalog</a>  </li>
+    <li><a href="../../userguide/transports.html" title="Transports Catalog"><span class="none"></span>Transports Catalog</a>  </li>
+    <li><a href="../../userguide/properties.html" title="Properties Catalog"><span class="none"></span>Properties Catalog</a>  </li>
+    <li><a href="../../userguide/xpath.html" title="XPath functions and Variables"><span class="none"></span>XPath functions and Variables</a>  </li>
+    <li><a href="../../userguide/extending.html" title="Extending Synapse"><span class="none"></span>Extending Synapse</a>  </li>
+    <li><a href="../../userguide/template_library.html" title="Synapse Template Libraries"><span class="none"></span>Synapse Template Libraries</a>  </li>
+    <li><a href="../../userguide/upgrading.html" title="Upgrading"><span class="none"></span>Upgrading</a>  </li>
+    <li><a href="../../userguide/deployment.html" title="Deployment"><span class="none"></span>Deployment</a>  </li>
+    <li><a href="../../apidocs/" title="Javadocs"><span class="none"></span>Javadocs</a>  </li>
+    <li><a href="../../userguide/faq.html" title="FAQ"><span class="none"></span>FAQ</a>  </li>
+          <li class="nav-header">Developer Resources</li>
+    <li><a href="../../dev/developer-guide.html" title="Developer Guide"><span class="none"></span>Developer Guide</a>  </li>
+    <li><a href="../../dev/best-practices.html" title="Development Best Practices"><span class="none"></span>Development Best Practices</a>  </li>
+    <li><a href="../../dev/release-process.html" title="Release Process"><span class="none"></span>Release Process</a>  </li>
+          <li class="nav-header">Project Details</li>
+    <li><a href="../../project-info.html" title="Overview"><span class="none"></span>Overview</a>  </li>
+    <li><a href="../../mail-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a>  </li>
+    <li><a href="../../source-repository.html" title="Source Repository"><span class="none"></span>Source Repository</a>  </li>
+    <li><a href="../../issue-tracking.html" title="Issue Tracking"><span class="none"></span>Issue Tracking</a>  </li>
+    <li><a href="../../dependency-management.html" title="Dependencies"><span class="none"></span>Dependencies</a>  </li>
+    <li><a href="../../team-list.html" title="Project Team"><span class="none"></span>Project Team</a>  </li>
+  </ul>
+          <hr />
+          <div id="poweredBy">
+              <div class="clear"></div>
+              <div class="clear"></div>
+              <div class="clear"></div>
+              <div class="clear"></div>
+  <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../../images/logos/maven-feather.png" /></a>
+              </div>
+          </div>
+        </div>
+        <div id="bodyColumn"  class="span10" >
+
+    
+        <a name="Contents"></a>
+<div class="section" id="Contents">
+<h2><a name="Pass_Through_HTTP_Transport"></a>Pass Through HTTP Transport</h2>
+            
+<ul>
+                
+<li>
+                    <a href="#Introduction">Introduction</a>
+                </li>
+                
+<li>
+                    <a href="#Configuration">Transport Configuration</a>
+                    
+<ul>
+                        
+<li><a href="#HTTPListener">HTTP Transport Listener</a></li>
+                        
+<li><a href="#HTTPSender">HTTP Transport Sender</a></li>
+                        
+<li><a href="#HTTPSListener">HTTPS Transport Listener</a></li>
+                        
+<li><a href="#HTTPSSender">HTTPS Transport Sender</a></li>
+                    </ul>
+                </li>
+                
+<li>
+                    <a href="#AdvancedSettings">Advanced Settings and Performance Tuning</a>
+                    
+<ul>
+                        
+<li><a href="#HttpCoreSettings">Apache HTTP Core Settings</a></li>
+                        
+<li><a href="#SynapseSettings">Synapse HTTP Mediation Settings</a></li>
+                        
+<li><a href="#ThreadPoolSettings">Thread Pool Settings</a></li>
+                        
+<li><a href="#AdvancedGuidelines">Guidelines for Using Advanced Settings</a></li>
+                        
+<li><a href="#LinuxSettings">Unix/Linux Specific Settings</a></li>
+                    </ul>
+                </li>
+                
+<li>
+                    <a href="#Logging">Logging Configuration</a>
+                    
+<ul>
+                        
+<li><a href="#LoggingGuidelines">Guidelines for Using Advanced Logging</a></li>
+                    </ul>
+                </li>
+                
+<li>
+                    <a href="#JMX">Monitoring with JMX</a>
+                    
+<ul>
+                        
+<li><a href="#ConnectionsView">ConnectionsView (org.apache.synapse.PassThroughConnections)</a></li>
+                        
+<li><a href="#LatencyView">LatencyView (org.apache.synapse.PassThroughTransportLatency)</a></li>
+                        
+<li><a href="#TransportView">TransportView (org.apache.synapse.Transport)</a></li>
+                    </ul>
+                </li>
+            </ul>
+        </div>
+        <a name="Introduction"></a>
+<div class="section" id="Introduction">
+<h2><a name="Introduction"></a>Introduction</h2>
+            
+<p>
+                The Pass Through HTTP transport (PTHTTP transport) was developed by
+                <a class="externalLink" 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 or not, 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 class="externalLink" href="http://en.wikipedia.org/wiki/Reactor_pattern">reactor pattern</a>,
+                and the PTHTTP transport uses two separate reactor instances:
+                </p>
+<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><a href="#Contents">[Back to top]</a></p>
+        </div>
+        <a name="Configuration"></a>
+<div class="section" id="Configuration">
+<h2><a name="Transport_Configuration"></a>Transport Configuration</h2>
+            
+<p>
+                Pass Through HTTP transport is configured by default in the
+                <b>SYNAPSE_HOME/repository/conf/axis2.xml</b>
+                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>
+            <a name="HTTPListener"></a>
+<div class="section" id="HTTPListener">
+<h3><a name="HTTP_Transport_Listener"></a>HTTP Transport Listener</h3>
+                
+<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=&quot;http&quot; class=&quot;org.apache.synapse.transport.passthru.PassThroughHttpListener&quot;&gt;
+    &lt;parameter name=&quot;port&quot;&gt;8280&lt;/parameter&gt;
+    &lt;parameter name=&quot;httpGetProcessor&quot; locked=&quot;false&quot;&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 border="0" class="table table-striped">
+                    
+<tr class="a">
+                        
+<th>Parameter Name</th>
+                        
+<th>Description/Example</th>
+                        
+<th>Required</th>
+                        
+<th>Default</th>
+                    </tr>
+                    
+<tr class="b">
+                        
+<td>port</td>
+                        
+<td>
+                            The port number on which the HTTP listener should listen.
+                            
+<div class="xmlConf">&lt;parameter name=&quot;port&quot;&gt;8280&lt;/parameter&gt;</div>
+                        </td>
+                        
+<td>Yes</td>
+                        
+<td>N/A</td>
+                    </tr>
+                    
+<tr class="a">
+                        
+<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=&quot;bind-address&quot;&gt;10.0.0.5&lt;/parameter&gt;</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>All available network interfaces</td>
+                    </tr>
+                    
+<tr class="b">
+                        
+<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=&quot;hostname&quot;&gt;10.0.0.5&lt;/parameter&gt;</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>localhost</td>
+                    </tr>
+                    
+<tr class="a">
+                        
+<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=&quot;WSDLEPRPrefix&quot;&gt;http://proxy.example.com:8080/&lt;/parameter&gt;</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>http://&lt;host&gt;:&lt;port&gt;/</td>
+                    </tr>
+                    
+<tr class="b">
+                        
+<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=&quot;httpGetProcessor&quot;&gt;foo.bar.CustomGETProcessor&lt;/parameter&gt;</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>N/A</td>
+                    </tr>
+                </table>
+                
+<p>
+                    All the above parameters are also applicable to the HTTPS transport listener.
+                </p>
+                
+<p><a href="#Contents">[Back to top]</a></p>
+            </div>
+            <a name="HTTPSender"></a>
+<div class="section" id="HTTPSender">
+<h3><a name="HTTP_Transport_Sender"></a>HTTP Transport Sender</h3>
+                
+<p>
+                    The default Pass Through HTTP sender configuration available in the axis2.xml
+                    file is shown below.
+                </p>
+                
+<div class="xmlConf">&lt;transportSender name=&quot;http&quot;  class=&quot;org.apache.synapse.transport.passthru.PassThroughHttpSender&quot; /&gt;</div>
+                
+<p>
+                    Following parameters can be specified to customize the behavior of the HTTP
+                    sender.
+                </p>
+                
+<table border="0" class="table table-striped">
+                    
+<tr class="a">
+                        
+<th>Parameter Name</th>
+                        
+<th>Description/Example</th>
+                        
+<th>Required</th>
+                        
+<th>Default</th>
+                    </tr>
+                    
+<tr class="b">
+                        
+<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=&quot;http.proxyHost&quot;&gt;proxy.example.com&lt;/parameter&gt;</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>N/A</td>
+                    </tr>
+                    
+<tr class="a">
+                        
+<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=&quot;http.proxyPort&quot;&gt;8080&lt;/parameter&gt;</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>80</td>
+                    </tr>
+                    
+<tr class="b">
+                        
+<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=&quot;http.nonProxyHosts&quot;&gt;10.0.0.8|foo.com|*.bar.org&lt;/parameter&gt;</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>N/A</td>
+                    </tr>
+                </table>
+                
+<p><a href="#Contents">[Back to top]</a></p>
+            </div>
+            <a name="HTTPSListener"></a>
+<div class="section" id="HTTPSListener">
+<h3><a name="HTTPS_Transport_Listener"></a>HTTPS Transport Listener</h3>
+                
+<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=&quot;https&quot; class=&quot;org.apache.synapse.transport.passthru.PassThroughHttpSSLListener&quot;&gt;
+    &lt;parameter name=&quot;port&quot; locked=&quot;false&quot;&gt;8243&lt;/parameter&gt;
+    &lt;parameter name=&quot;httpGetProcessor&quot; locked=&quot;false&quot;&gt;org.apache.synapse.transport.passthru.api.PassThroughNHttpGetProcessor&lt;/parameter&gt;
+    &lt;parameter name=&quot;keystore&quot; locked=&quot;false&quot;&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=&quot;truststore&quot; locked=&quot;false&quot;&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 border="0" class="table table-striped">
+                    
+<tr class="a">
+                        
+<th>Parameter Name</th>
+                        
+<th>Description/Example</th>
+                        
+<th>Required</th>
+                        
+<th>Default</th>
+                    </tr>
+                    
+<tr class="b">
+                        
+<td>port</td>
+                        
+<td>
+                            The port number on which the HTTPS listener should listen.
+                            
+<div class="xmlConf">&lt;parameter name=&quot;port&quot;&gt;8243&lt;/parameter&gt;</div>
+                        </td>
+                        
+<td>Yes</td>
+                        
+<td>N/A</td>
+                    </tr>
+                    
+<tr class="a">
+                        
+<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 class="externalLink" href="http://docs.oracle.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html">Java Cryptography Architecture</a>
+                            specification.
+                            <br />
+                            <br />
+                            <b>
+                                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.
+                            </b>
+                            
+<div class="xmlConf">&lt;parameter name=&quot;keystore&quot; locked=&quot;false&quot;&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 class="b">
+                        
+<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 class="externalLink" href="http://docs.oracle.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html">Java Cryptography Architecture</a>
+                            specification.
+                            <br />
+                            <br />
+                            <b>
+                                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.
+                            </b>
+                            
+<div class="xmlConf">&lt;parameter name=&quot;truststore&quot; locked=&quot;false&quot;&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 class="a">
+                        
+<td>SSLVerifyClient</td>
+                        
+<td>
+                            Use this parameter to enable client certificate verification (client
+                            authentication). This option provides functionality similar to the
+                            <a class="externalLink" 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=&quot;SSLVerifyClient&quot;&gt;require&lt;/parameter&gt;</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>None</td>
+                    </tr>
+                    
+<tr class="b">
+                        
+<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=&quot;bind-address&quot;&gt;10.0.0.5&lt;/parameter&gt;</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>All available network interfaces</td>
+                    </tr>
+                    
+<tr class="a">
+                        
+<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=&quot;hostname&quot;&gt;10.0.0.5&lt;/parameter&gt;</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>localhost</td>
+                    </tr>
+                    
+<tr class="b">
+                        
+<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=&quot;httpGetProcessor&quot;&gt;foo.bar.CustomGETProcessor&lt;/parameter&gt;</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>N/A</td>
+                    </tr>
+                    
+<tr class="a">
+                        
+<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=&quot;WSDLEPRPrefix&quot;&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>
+                
+<p><a href="#Contents">[Back to top]</a></p>
+            </div>
+            <a name="HTTPSSender"></a>
+<div class="section" id="HTTPSSender">
+<h3><a name="HTTPS_Transport_Sender"></a>HTTPS Transport Sender</h3>
+                
+<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=&quot;https&quot; class=&quot;org.apache.synapse.transport.passthru.PassThroughHttpSSLSender&quot;&gt;
+    &lt;parameter name=&quot;keystore&quot; locked=&quot;false&quot;&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=&quot;truststore&quot; locked=&quot;false&quot;&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 border="0" class="table table-striped">
+                    
+<tr class="a">
+                        
+<th>Parameter Name</th>
+                        
+<th>Description/Example</th>
+                        
+<th>Required</th>
+                        
+<th>Default</th>
+                    </tr>
+                    
+<tr class="b">
+                        
+<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 class="externalLink" href="http://docs.oracle.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html">Java Cryptography Architecture</a>
+                            specification.
+                            <br />
+                            <br />
+                            <b>
+                                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.
+                            </b>
+                            
+<div class="xmlConf">&lt;parameter name=&quot;keystore&quot; locked=&quot;false&quot;&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 class="a">
+                        
+<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 class="externalLink" href="http://docs.oracle.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html">Java Cryptography Architecture</a>
+                            specification.
+                            <br />
+                            <br />
+                            <b>
+                                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.
+                            </b>
+                            
+<div class="xmlConf">&lt;parameter name=&quot;truststore&quot; locked=&quot;false&quot;&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 class="b">
+                        
+<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 class="externalLink" 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=&quot;HostnameVerifier&quot;&gt;Strict&lt;/parameter&gt;</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>Default</td>
+                    </tr>
+                    
+<tr class="a">
+                        
+<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=&quot;novalidatecert&quot;&gt;true&lt;/parameter&gt;</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>false</td>
+                    </tr>
+                    
+<tr class="b">
+                        
+<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=&quot;customSSLProfiles&quot;&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 class="a">
+                        
+<td>CertificateRevocationVerifier</td>
+                        
+<td>
+                            Enable revocation status validation of server certificates using
+                            <a class="externalLink" href="http://www.ietf.org/rfc/rfc2560.txt">OCSP</a> and
+                            <a class="externalLink" 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: Sets 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=&quot;CertificateRevocationVerifier&quot; locked=&quot;false&quot;&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>
+                
+<p><a href="#Contents">[Back to top]</a></p>
+            </div>
+        </div>
+        <a name="AdvancedSettings"></a>
+<div class="section" id="AdvancedSettings">
+<h2><a name="Advanced_Settings_and_Performance_Tuning"></a>Advanced Settings and Performance Tuning</h2>
+            
+<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 should be configured in the
+                <b>SYNAPSE_HOME/lib/passthru-http.properties</b> file. 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
+                sections describe all the advanced options that can be set for the Pass Through
+                HTTP transport.
+            </p>
+            <a name="HttpCoreSettings"></a>
+<div class="section" id="HttpCoreSettings">
+<h3><a name="Apache_HTTP_Core_Settings"></a>Apache HTTP Core Settings</h3>
+                
+<p>
+                    Following properties control various facets of
+                    <a class="externalLink" href="http://hc.apache.org/httpcomponents-core-ga/index.html">Apache HTTP Core</a>,
+                    the framework underlying the Pass Through HTTP transport.
+                </p>
+                
+<table border="0" class="table table-striped">
+                    
+<tr class="a">
+                        
+<th>Parameter Name</th>
+                        
+<th>Description/Example</th>
+                        
+<th>Required</th>
+                        
+<th>Default</th>
+                    </tr>
+                    
+<tr class="b">
+                        
+<td>http.socket.timeout <a name="http.socket.timeout"></a></td>
+                        
+<td>
+                            Sets the TCP socket timeout in milliseconds
+                            (See <a class="externalLink" href="http://docs.oracle.com/javase/1.5.0/docs/api/java/net/SocketOptions.html#SO_TIMEOUT">SO_TIMEOUT</a>).
+                            This applies to sockets opened by both transport listener and sender.
+                            
+<div class="xmlConf">http.socket.timeout=20000</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>60000</td>
+                    </tr>
+                    
+<tr class="a">
+                        
+<td>http.socket.timeout.listener</td>
+                        
+<td>
+                            Sets the timeout in milliseconds for all the TCP sockets opened by the
+                            transport listener. This overrides the value of
+                            <a href="#http.socket.timeout">http.socket.timeout</a> for the transport
+                            listener.
+                            
+<div class="xmlConf">http.socket.timeout.listener=20000</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>Value of <a href="#http.socket.timeout">http.socket.timeout</a></td>
+                    </tr>
+                    
+<tr class="b">
+                        
+<td>http.socket.timeout.sender</td>
+                        
+<td>
+                            Sets the timeout in milliseconds for all the TCP sockets opened by the
+                            transport sender. This overrides the value of
+                            <a href="#http.socket.timeout">http.socket.timeout</a> for the transport
+                            sender.
+                            
+<div class="xmlConf">http.socket.timeout.sender=20000</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>Value of <a href="#http.socket.timeout">http.socket.timeout</a></td>
+                    </tr>
+                    
+<tr class="a">
+                        
+<td>http.connection.timeout</td>
+                        
+<td>
+                            Sets 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 class="b">
+                        
+<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 class="externalLink" 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 class="a">
+                        
+<td>http.tcp.nodelay</td>
+                        
+<td>
+                            Setting this property to 'true' disables
+                            <a class="externalLink" href="http://en.wikipedia.org/wiki/Nagle&apos;s_algorithm">Nagle's algorithm</a>
+                            for the HTTP connections. That is, outgoing data will not be buffered
+                            and aggregated together
+                            (See <a class="externalLink" 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 class="b">
+                        
+<td>http.socket.buffer-size</td>
+                        
+<td>
+                            Sets the size of the I/O session buffers (in bytes) used by the transport
+                            for reading incoming data and writing outgoing data.
+                            
+<div class="xmlConf">http.socket.buffer-size=4096</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>8192</td>
+                    </tr>
+                    
+<tr class="a">
+                        
+<td>http.socket.rcv-buffer-size</td>
+                        
+<td>
+                            Sets the size of the buffers (in bytes) 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 class="externalLink" href="http://docs.oracle.com/javase/1.5.0/docs/api/java/net/SocketOptions.html#SO_RCVBUF">SO_RCVBUF</a>).
+                            If no value is specified, Synapse will use the platform (OS) default.
+                            
+<div class="xmlConf">http.socket.rcv-buffer-size=8192</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>Platform default</td>
+                    </tr>
+                    
+<tr class="b">
+                        
+<td>http.socket.snd-buffer-size</td>
+                        
+<td>
+                            Sets the size of the buffers (in bytes) 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 class="externalLink" href="http://docs.oracle.com/javase/1.5.0/docs/api/java/net/SocketOptions.html#SO_SNDBUF">SO_SNDBUF</a>).
+                            If no value is specified, Synapse will use the platform (OS) default.
+                            
+<div class="xmlConf">http.socket.snd-buffer-size=8192</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>Platform default</td>
+                    </tr>
+                    
+<tr class="a">
+                        
+<td>http.socket.linger</td>
+                        
+<td>
+                            Specifies 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 class="externalLink" 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 class="b">
+                        
+<td>http.socket.reuseaddr</td>
+                        
+<td>
+                            Sets the <a class="externalLink" 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 class="a">
+                        
+<td>http.nio.select-interval</td>
+                        
+<td>
+                            Sets 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 class="b">
+                        
+<td>io_threads_per_reactor <a name="io_threads_per_reactor"></a></td>
+                        
+<td>
+                            Sets 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 class="a">
+                        
+<td>http.malformed.input.action</td>
+                        
+<td>
+                            Specifies 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 class="externalLink" 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 class="b">
+                        
+<td>http.unmappable.input.action</td>
+                        
+<td>
+                            Specifies 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 class="externalLink" 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>
+                </table>
+                
+<p><a href="#Contents">[Back to top]</a></p>
+            </div>
+            <a name="SynapseSettings"></a>
+<div class="section" id="SynapseSettings">
+<h3><a name="Synapse_HTTP_Mediation_Settings"></a>Synapse HTTP Mediation Settings</h3>
+                
+<p>
+                    Following settings determine the behavior of Synapse with respect to mediating
+                    HTTP traffic.
+                </p>
+                
+<table border="0" class="table table-striped">
+                    
+<tr class="a">
+                        
+<th>Parameter Name</th>
+                        
+<th>Description/Example</th>
+                        
+<th>Required</th>
+                        
+<th>Default</th>
+                    </tr>
+                    
+<tr class="b">
+                        
+<td>io_buffer_size</td>
+                        
+<td>
+                            Sets the size of the I/O buffers (in bytes) used as the pipes between HTTP
+                            listener and sender. Typically, the HTTP listener would write the incoming
+                            message data to one of these buffers, and the sender would read from it to
+                            send the message out.
+                            
+<div class="xmlConf">io_buffer_size=10240</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>8192</td>
+                    </tr>
+                    
+<tr class="a">
+                        
+<td>http.max.connection.per.target</td>
+                        
+<td>
+                            Determines the maximum number of HTTP connections the transport is
+                            allowed to maintain per target HTTP host (i.e. host:port pair). Used to
+                            control the number of connections created by the Pass Through transport
+                            for each endpoint.
+                            
+<div class="xmlConf">http.max.connection.per.target=1000</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td><a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/lang/Integer.html#MAX_VALUE">Integer.MAX_VALUE</a></td>
+                    </tr>
+                    
+<tr class="b">
+                        
+<td>http.user.agent.value <a name="http.user.agent.value"></a></td>
+                        
+<td>
+                            Specifies the string that should be used as the value of the HTTP User-Agent
+                            header for outgoing requests. If the request already has a User-Agent
+                            header (sent by the client), and the
+                            <a href="#http.user.agent.preserve">http.user.agent.preserve</a> property
+                            is set to true, this property will be ignored.
+                            
+<div class="xmlConf">http.user.agent.value=Finance-Data-Client</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>Synapse-PT-HttpComponents-NIO</td>
+                    </tr>
+                    
+<tr class="a">
+                        
+<td>http.server.value <a name="http.server.value"></a></td>
+                        
+<td>
+                            Specifies the string that should be used as the value of the HTTP Server
+                            header for outgoing responses. If the response already has a Server
+                            header (sent by the backend server), and the
+                            <a href="#http.server.preserve">http.server.preserve</a> property
+                            is set to true, this property will be ignored.
+                            
+<div class="xmlConf">http.server.value=Media-Gateway-Server</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>Synapse-PT-HttpComponents-NIO</td>
+                    </tr>
+                    
+<tr class="b">
+                        
+<td>http.user.agent.preserve <a name="http.user.agent.preserve"></a></td>
+                        
+<td>
+                            Specifies whether Synapse should preserve the User-Agent header sent by the
+                            client applications, when forwarding messages to backend servers. Allowed
+                            values are either true or false. If set to false, Synapse will overwrite
+                            the original User-Agent header value with the value of the
+                            <a href="#http.user.agent.value">http.user.agent.value</a> property.
+                            
+<div class="xmlConf">http.user.agent.preserve=true</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>false</td>
+                    </tr>
+                    
+<tr class="a">
+                        
+<td>http.server.preserve <a name="http.server.preserve"></a></td>
+                        
+<td>
+                            Specifies whether Synapse should preserve the Server header sent by the
+                            backend servers, when forwarding messages to client applications. Allowed
+                            values are either true or false. If set to false, Synapse will overwrite
+                            the original Server header value with the value of the
+                            <a href="#http.server.value">http.server.value</a> property.
+                            
+<div class="xmlConf">http.server.preserve=false</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>true</td>
+                    </tr>
+                </table>
+                
+<p><a href="#Contents">[Back to top]</a></p>
+            </div>
+            <a name="ThreadPoolSettings"></a>
+<div class="section" id="ThreadPoolSettings">
+<h3><a name="Thread_Pool_Settings"></a>Thread Pool Settings</h3>
+                
+<p>
+                    The Pass Through HTTP transport uses a thread pool for mediating messages
+                    through the Synapse mediation engine. 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.
+                </p>
+                
+<table border="0" class="table table-striped">
+                    
+<tr class="a">
+                        
+<th>Parameter Name</th>
+                        
+<th>Description/Example</th>
+                        
+<th>Required</th>
+                        
+<th>Default</th>
+                    </tr>
+                    
+<tr class="b">
+                        
+<td>worker_pool_size_core <a name="worker_pool_size_core"></a></td>
+                        
+<td>
+                            Set the core size of the thread pool used by the Pass Through HTTP
+                            transport. The thread pool starts with 0 threads, and grows in size as
+                            new tasks are submitted to it. Once the number of threads reaches or
+                            exceeds the core size, the thread pool will not allow the thread count
+                            to go below the core size. That is, the thread pool keeps the core amount
+                            of threads in the pool even if they are idle.
+                            
+<div class="xmlConf">worker_pool_size_core=100</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>40</td>
+                    </tr>
+                    
+<tr class="a">
+                        
+<td>worker_pool_size_max <a name="worker_pool_size_max"></a></td>
+                        
+<td>
+                            The thread pool used by the Pass Through HTTP transport grows in size, as
+                            more and more tasks 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 value of <a href="#worker_pool_size_core">worker_pool_size_core</a>.
+                            
+<div class="xmlConf">worker_pool_size_max=500</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>200</td>
+                    </tr>
+                    
+<tr class="b">
+                        
+<td>worker_thread_keepalive_sec</td>
+                        
+<td>
+                            Specifies the idle time period (in seconds) for the excess threads in
+                            the Pass Through transport thread pool. When the number of threads in the
+                            pool is greater than <a href="#worker_pool_size_core">worker_pool_size_core</a>,
+                            this is the maximum time that excess idle threads will wait for new tasks
+                            before terminating.
+                            
+<div class="xmlConf">worker_thread_keepalive_sec=10</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>60</td>
+                    </tr>
+                    
+<tr class="a">
+                        
+<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. The thread pool starts
+                            queueing jobs, when all the existing threads are busy and the pool has
+                            already reached the maximum number of threads.
+                            
+<div class="xmlConf">worker_pool_queue_length=1000</div>
+                        </td>
+                        
+<td>No</td>
+                        
+<td>-1</td>
+                    </tr>
+                </table>
+                
+<p><a href="#Contents">[Back to top]</a></p>
+            </div>
+            <a name="AdvancedGuidelines"></a>
+<div class="section" id="AdvancedGuidelines">
+<h3><a name="Guidelines_for_Using_Advanced_Settings"></a>Guidelines for Using Advanced Settings</h3>
+                
+<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 for
+                    each of the above settings, and these defaults will deliver good performance in
+                    most scenarios. However, to obtain 'best' performance from the Pass Through HTTP
+                    transport, it is recommended to tweak the above values. At least, consider tuning
+                    the <a href="#worker_pool_size_core">worker_pool_size_core</a> and
+                    <a href="#worker_pool_size_max">worker_pool_size_max</a> to match the expected
+                    load in your deployment.
+                </p>
+                
+<p>
+                    You might be tempted to configure the transport with a very large thread pool
+                    (e.g. 1000's of threads). But bare in mind that more threads equal more memory
+                    usage. Also, on some operating systems there are restrictions on the number of
+                    threads that can be spawned by an application. Therefore, do not attempt to set
+                    the thread pool size to an unnecessarily large value. Do a rough estimate of your
+                    expected workload (expected number of concurrent users), and set the thread pool
+                    size accordingly. As for setting the number of I/O dispatcher threads
+                    (<a href="#io_threads_per_reactor">io_threads_per_reactor</a>), setting it to
+                    match the number of available CPU cores generally results in good performance.
+                    Synapse does this for you by default, so you shouldn't have to do any extra work
+                    with regard to this property.
+                </p>
+                
+<p>
+                    It is highly recommended to run some load tests on Synapse using your own mediation
+                    configurations (sequences, proxy services etc.) on the actual production hardware.
+                    This will give you a much clear idea about what transport level properties need to
+                    be tuned up in your deployment.
+                </p>
+                
+<p><a href="#Contents">[Back to top]</a></p>
+            </div>
+            <a name="LinuxSettings"></a>
+<div class="section" id="LinuxSettings">
+<h3><a name="UnixLinux_Specific_Settings"></a>Unix/Linux Specific Settings</h3>
+                
+<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 prove to be useful.
+                </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>
+                
+<p><a href="#Contents">[Back to top]</a></p>
+            </div>
+        </div>
+        <a name="Logging"></a>
+<div class="section" id="Logging">
+<h2><a name="Logging_Configuration"></a>Logging Configuration</h2>
+            
+<p>
+                <b>Note: This section is applicable to both Pass Through and NHTTP transports of
+                Synapse.</b>
+            </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 class="externalLink" 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 <b>SYNAPSE_HOME/lib/log4j.properties</b>
+                file of the 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>
+            
+<p><a href="#Contents">[Back to top]</a></p>
+            <a name="LoggingGuidelines"></a>
+<div class="section" id="LoggingGuidelines">
+<h3><a name="Guidelines_for_Using_Advanced_Logging"></a>Guidelines for Using Advanced Logging</h3>
+                
+<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>
+                
+<p><a href="#Contents">[Back to top]</a></p>
+            </div>
+        </div>
+        <a name="JMX"></a>
+<div class="section" id="JMX">
+<h2><a name="Monitoring_with_JMX"></a>Monitoring with JMX</h2>
+            
+<p>
+                Pass Through HTTP transport exposes several JMX MBeans, which can be used to obtain
+                crucial statistical information about how the transport performs. This includes the
+                number of inbound and outbound connections opened by the transport, the number of
+                HTTP messages mediated, distribution of the message sizes and the latency incurred

[... 599 lines stripped ...]


Mime
View raw message