You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@synapse.apache.org by ra...@apache.org on 2017/01/04 10:30:07 UTC
svn commit: r1777276 [11/12] - in /synapse/site: css/ fonts/ images/
images/profiles/ img/ js/ userguide/ userguide/samples/ userguide/transports/
Added: synapse/site/userguide/transports/pass_through.html
URL: http://svn.apache.org/viewvc/synapse/site/userguide/transports/pass_through.html?rev=1777276&view=auto
==============================================================================
--- synapse/site/userguide/transports/pass_through.html (added)
+++ synapse/site/userguide/transports/pass_through.html Wed Jan 4 10:30:06 2017
@@ -0,0 +1,2729 @@
+<!DOCTYPE html>
+<!--
+ | Generated by Apache Maven Doxia at 2017-01-04
+ | Rendered using Apache Maven Fluido Skin 1.4
+-->
+<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="20170104" />
+ <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.4.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.4.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-01-04
+ <span class="divider">|</span>
+ </li>
+ <li id="projectVersion">Version: 3.0.0
+ </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" >
+
+ <!-- ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License. -->
+
+ <a name="Contents"></a>
+<div class="section" id="Contents">
+<h2>Pass Through HTTP Transport<a name="Pass_Through_HTTP_Transport"></a></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>Introduction<a name="Introduction"></a></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>Transport Configuration<a name="Transport_Configuration"></a></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>HTTP Transport Listener<a name="HTTP_Transport_Listener"></a></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>HTTP Transport Sender<a name="HTTP_Transport_Sender"></a></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>HTTPS Transport Listener<a name="HTTPS_Transport_Listener"></a></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>HTTPS Transport Sender<a name="HTTPS_Transport_Sender"></a></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>Advanced Settings and Performance Tuning<a name="Advanced_Settings_and_Performance_Tuning"></a></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>Apache HTTP Core Settings<a name="Apache_HTTP_Core_Settings"></a></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>Synapse HTTP Mediation Settings<a name="Synapse_HTTP_Mediation_Settings"></a></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>Thread Pool Settings<a name="Thread_Pool_Settings"></a></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>Guidelines for Using Advanced Settings<a name="Guidelines_for_Using_Advanced_Settings"></a></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>Unix/Linux Specific Settings<a name="UnixLinux_Specific_Settings"></a></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>Logging Configuration<a name="Logging_Configuration"></a></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.
[... 685 lines stripped ...]