Added: synapse/site/3_0_2/userguide/transports/pass_through.html URL: http://svn.apache.org/viewvc/synapse/site/3_0_2/userguide/transports/pass_through.html?rev=1909775&view=auto ============================================================================== --- synapse/site/3_0_2/userguide/transports/pass_through.html (added) +++ synapse/site/3_0_2/userguide/transports/pass_through.html Fri May 12 16:09:34 2023 @@ -0,0 +1,2491 @@ +<!DOCTYPE html> +<!-- + | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2023-05-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="20230504" /> + <meta http-equiv="Content-Language" content="en" /> + <title>Apache Synapse – 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: 2023-05-04<span class="divider">|</span> +</li> + <li id="projectVersion">Version: 3.0.2</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"><transportReceiver name="http" class="org.apache.synapse.transport.passthru.PassThroughHttpListener"> + <parameter name="port">8280</parameter> + <parameter name="httpGetProcessor" locked="false">org.apache.synapse.transport.passthru.api.PassThroughNHttpGetProcessor</parameter> +</transportReceiver></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"><parameter name="port">8280</parameter></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"><parameter name="bind-address">10.0.0.5</parameter></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"><parameter name="hostname">10.0.0.5</parameter></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"><parameter name="WSDLEPRPrefix">http://proxy.example.com:8080/</parameter></div> + </td> + +<td>No</td> + +<td>http://<host>:<port>/</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"><parameter name="httpGetProcessor">foo.bar.CustomGETProcessor</parameter></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"><transportSender name="http" class="org.apache.synapse.transport.passthru.PassThroughHttpSender" /></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"><parameter name="http.proxyHost">proxy.example.com</parameter></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"><parameter name="http.proxyPort">8080</parameter></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"><parameter name="http.nonProxyHosts">10.0.0.8|foo.com|*.bar.org</parameter></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"><transportReceiver name="https" class="org.apache.synapse.transport.passthru.PassThroughHttpSSLListener"> + <parameter name="port" locked="false">8243</parameter> + <parameter name="httpGetProcessor" locked="false">org.apache.synapse.transport.passthru.api.PassThroughNHttpGetProcessor</parameter> + <parameter name="keystore" locked="false"> + <KeyStore> + <Location>lib/identity.jks</Location> + <Type>JKS</Type> + <Password>password</Password> + <KeyPassword>password</KeyPassword> + </KeyStore> + </parameter> + <parameter name="truststore" locked="false"> + <TrustStore> + <Location>lib/trust.jks</Location> + <Type>JKS</Type> + <Password>password</Password> + </TrustStore> + </parameter> +</transportReceiver></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"><parameter name="port">8243</parameter></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"><parameter name="keystore" locked="false"> + <KeyStore> + <Location>lib/identity.jks</Location> + <Type>JKS</Type> + <Password>password</Password> + <KeyPassword>password</KeyPassword> + </KeyStore> +</parameter></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"><parameter name="truststore" locked="false"> + <TrustStore> + <Location>lib/trust.jks</Location> + <Type>JKS</Type> + <Password>password</Password> + </TrustStore> +</parameter></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"><parameter name="SSLVerifyClient">require</parameter></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"><parameter name="bind-address">10.0.0.5</parameter></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"><parameter name="hostname">10.0.0.5</parameter></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"><parameter name="httpGetProcessor">foo.bar.CustomGETProcessor</parameter></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"><parameter name="WSDLEPRPrefix">https://proxy.example.com:8443/</parameter></div> + </td> + +<td>No</td> + +<td>https://<host>:<port>/</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"><transportSender name="https" class="org.apache.synapse.transport.passthru.PassThroughHttpSSLSender"> + <parameter name="keystore" locked="false"> + <KeyStore> + <Location>lib/identity.jks</Location> + <Type>JKS</Type> + <Password>password</Password> + <KeyPassword>password</KeyPassword> + </KeyStore> + </parameter> + <parameter name="truststore" locked="false"> + <TrustStore> + <Location>lib/trust.jks</Location> + <Type>JKS</Type> + <Password>password</Password> + </TrustStore> + </parameter> +</transportSender></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"><parameter name="keystore" locked="false"> + <KeyStore> + <Location>lib/identity.jks</Location> + <Type>JKS</Type> + <Password>password</Password> + <KeyPassword>password</KeyPassword> + </KeyStore> +</parameter></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"><parameter name="truststore" locked="false"> + <TrustStore> + <Location>lib/trust.jks</Location> + <Type>JKS</Type> + <Password>password</Password> + </TrustStore> +</parameter></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"><parameter name="HostnameVerifier">Strict</parameter></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"><parameter name="novalidatecert">true</parameter></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"><parameter name="customSSLProfiles"> + <profile> + <servers>server1.example.com:443,server2.example.com:443</servers> + <KeyStore> + <Location>lib/identity1.jks</Location> + <Type>JKS</Type> + <Password>password</Password> + <KeyPassword>password</KeyPassword> + </KeyStore> + <TrustStore> + <Location>lib/trust1.jks</Location> + <Type>JKS</Type> + <Password>password</Password> + </TrustStore> + </profile> + <profile> + <servers>server3.example.com:443</servers> + <KeyStore> + <Location>lib/identity2.jks</Location> + <Type>JKS</Type> + <Password>password</Password> + <KeyPassword>password</KeyPassword> + </KeyStore> + <TrustStore> + <Location>lib/trust2.jks</Location> + <Type>JKS</Type> + <Password>password</Password> + </TrustStore> + </profile> +</parameter></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"><parameter name="CertificateRevocationVerifier" locked="false"> + <CacheSize>100</CacheSize> + <CacheDurationMins></CacheDurationMins> +</parameter></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'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 ...]
