<?xml version="1.0" encoding="ISO-8859-1" ?>

<!--
  ~  Licensed to the Apache Software Foundation (ASF) under one
  ~  or more contributor license agreements.  See the NOTICE file
  ~  distributed with this work for additional information
  ~  regarding copyright ownership.  The ASF licenses this file
  ~  to you under the Apache License, Version 2.0 (the
  ~  "License"); you may not use this file except in compliance
  ~  with the License.  You may obtain a copy of the License at
  ~
  ~   http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~  Unless required by applicable law or agreed to in writing,
  ~  software distributed under the License is distributed on an
  ~   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~  KIND, either express or implied.  See the License for the
  ~  specific language governing permissions and limitations
  ~  under the License.
  -->

<document>
    <properties>
        <title>Apache Synapse - Pass Through HTTP Transport</title>
    </properties>
    <body>
        <section name="Pass Through HTTP Transport" id="Contents">
            <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>
        </section>
        <section name="Introduction" id="Introduction">
            <p>
                The Pass Through HTTP transport (PTHTTP transport) was developed by
                <a href="http://wso2.com">WSO2</a> as a more efficient and more scalable
                alternative to the standard Non-blocking HTTP transport (NHTTP transport) of
                Synapse. The PTHTTP transport was later contributed to the Synapse project,
                and was made the default HTTP transport of the Synapse ESB. All versions of
                Synapse released after version 2.1, use the PTHTTP transport by default to
                receive and send HTTP messages.
            </p>
            <p>
                The PTHTTP transport was originally designed to facilitate content agnostic (pass
                through) HTTP mediation in a highly efficient manner. That is, it mediates
                HTTP messages without reading the message body. A number of enterprise integration
                scenarios (e.g. header-based routing, load balancing, URL rewriting) require
                efficient means of content agnostic mediation, and the standard NHTTP transport of
                Synapse is somewhat inefficient when supporting such use cases. The dual-buffer I/O
                model of the NHTTP transport induces unnecessary copying of message payload data
                between buffers, and it by default parses all received messages using the Axis2
                message builder framework. The PTHTTP transport was originally designed with a
                single-buffer I/O model, and it skips the Axis2 message builder framework altogether.
                Therefore, the PTHTTP transport delivers excellent throughput and minimal latency
                when it comes to content agnostic mediation scenarios.
            </p>
            <p>
                However, the original PTHTTP transport did not support any mediation scenario that
                requires accessing message payload data (e.g. content-based routing, XSLT
                transformation). In order to overcome this limitation, a number of architectural
                improvements were introduced to the Synapse mediation engine. These enhancements
                enable Synapse to use the PTHTTP transport as the default HTTP transport. Now Synapse
                uses a single buffer and does not invoke the Axis2 builders for all content agnostic
                mediation flows, but for content-aware mediation flows, it transparently falls back
                to the dual-buffer mode and engages the Axis2 message builder framework. Individual
                mediators in a message flow (sequence, proxy service) decide whether to invoke the
                Axis2 message builders 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 href="http://en.wikipedia.org/wiki/Reactor_pattern">reactor pattern</a>,
                and the PTHTTP transport uses two separate reactor instances:
                <ul>
                    <li>
                        Listening I/O reactor: Handles network interactions between client
                        applications and Synapse.
                    </li>
                    <li>
                        Connecting I/O reactor: Handles network interactions between Synapse and
                        the backend services.
                    </li>
                </ul>
                Each reactor instance uses its own set of threads and in addition, the PTHTTP transport
                uses a separate configurable thread pool for processing received messages through
                the mediation engine. Settings related to configuring I/O reactor threads and PTHTTP
                threads are discussed under <a href="#AdvancedSettings">advanced settings</a>.
            </p>
            <p><a href="#Contents">[Back to top]</a></p>
        </section>
        <section name="Transport Configuration" id="Configuration">
            <p>
                Pass Through HTTP transport is configured by default in the
                <strong>SYNAPSE_HOME/repository/conf/axis2.xml</strong>
                file of Synapse. The default configuration activates the following four components:
            </p>
            <ul>
                <li>HTTP transport listener</li>
                <li>HTTP transport sender</li>
                <li>HTTPS transport listener</li>
                <li>HTTPS transport sender</li>
            </ul>
            <p>
                Each of the above components are configured separately in the axis2.xml file. Next
                few sections describe the various parameters that can be used to customize the
                behavior of these components.
            </p>
            <subsection name="HTTP Transport Listener" id="HTTPListener">
                <p>
                    The default configuration of the Pass Through HTTP listener is shown
                    below, as it appears in the axis2.xml file.
                </p>
                <div class="xmlConf">&lt;transportReceiver name="http" class="org.apache.synapse.transport.passthru.PassThroughHttpListener"&gt;
    &lt;parameter name="port"&gt;8280&lt;/parameter&gt;
    &lt;parameter name="httpGetProcessor" locked="false"&gt;org.apache.synapse.transport.passthru.api.PassThroughNHttpGetProcessor&lt;/parameter&gt;
&lt;/transportReceiver&gt;</div>
                <p>
                    The default configuration, simply sets the HTTP port to 8280 and specifies the
                    name of the class responsible for processing incoming HTTP GET requests. A
                    complete listing of supported parameters is given below.
                </p>
                <table>
                    <tr>
                        <th>Parameter Name</th>
                        <th>Description/Example</th>
                        <th>Required</th>
                        <th>Default</th>
                    </tr>
                    <tr>
                        <td>port</td>
                        <td>
                            The port number on which the HTTP listener should listen.
                            <div class="xmlConf">&lt;parameter name="port"&gt;8280&lt;/parameter&gt;</div>
                        </td>
                        <td>Yes</td>
                        <td>N/A</td>
                    </tr>
                    <tr>
                        <td>bind-address</td>
                        <td>
                            The hostname or IP address to which the HTTP listener should bind. When
                            deploying Synapse on machines that have multiple network interfaces,
                            this parameter can be used to bind the HTTP listener to a specific network
                            interface.
                            <div class="xmlConf">&lt;parameter name="bind-address"&gt;10.0.0.5&lt;/parameter&gt;</div>
                        </td>
                        <td>No</td>
                        <td>All available network interfaces</td>
                    </tr>
                    <tr>
                        <td>hostname</td>
                        <td>
                            The hostname or IP address used to calculate the service endpoints
                            exposed through this transport listener. This can be used to customize
                            the hostname of the endpoints (EPRs) that appear in the generated WSDLs.
                            This parameter is ignored if the WSDLEPRPrefix parameter is set.
                            <div class="xmlConf">&lt;parameter name="hostname"&gt;10.0.0.5&lt;/parameter&gt;</div>
                        </td>
                        <td>No</td>
                        <td>localhost</td>
                    </tr>
                    <tr>
                        <td>WSDLEPRPrefix</td>
                        <td>
                            A URL prefix that should be added to all the HTTP endpoints exposed
                            through this transport listener. This prefix will appear in all WSDLs
                            advertised by the transport. This is particularly useful when Synapse
                            is fronted by a proxy server or a load balancer and it is required to mention
                            the proxy/load balancer endpoints in the WSDLs generated by Synapse. This
                            parameter has higher priority than the hostname parameter.
                            <div class="xmlConf">&lt;parameter name="WSDLEPRPrefix"&gt;http://proxy.example.com:8080/&lt;/parameter&gt;</div>
                        </td>
                        <td>No</td>
                        <td>http://&lt;host&gt;:&lt;port&gt;/</td>
                    </tr>
                    <tr>
                        <td>httpGetProcessor</td>
                        <td>
                            The full qualified name of the class that's responsible for handling incoming
                            HTTP GET requests. The specified class must implement the
                            org.apache.synapse.transport.passthru.HttpGetRequestProcessor interface. If it
                            is required to customize the way Synapse handles HTTP GET requests, one could
                            implement the above interface, and register the custom class with Synapse using
                            this parameter. By default Synapse ships with an HTTP GET request handler that
                            responds to ?wsdl and ?xsd requests and mediates all the others.
                            <div class="xmlConf">&lt;parameter name="httpGetProcessor"&gt;foo.bar.CustomGETProcessor&lt;/parameter&gt;</div>
                        </td>
                        <td>No</td>
                        <td>N/A</td>
                    </tr>
                </table>
                <p>
                    All the above parameters are also applicable to the HTTPS transport listener.
                </p>
                <p><a href="#Contents">[Back to top]</a></p>
            </subsection>
            <subsection name="HTTP Transport Sender" id="HTTPSender">
                <p>
                    The default Pass Through HTTP sender configuration available in the axis2.xml
                    file is shown below.
                </p>
                <div class="xmlConf">&lt;transportSender name="http"  class="org.apache.synapse.transport.passthru.PassThroughHttpSender" /&gt;</div>
                <p>
                    Following parameters can be specified to customize the behavior of the HTTP
                    sender.
                </p>
                <table>
                    <tr>
                        <th>Parameter Name</th>
                        <th>Description/Example</th>
                        <th>Required</th>
                        <th>Default</th>
                    </tr>
                    <tr>
                        <td>http.proxyHost</td>
                        <td>
                            The hostname or IP address of the proxy server through which the HTTP
                            messages should be sent. Use this property when Synapse should use an
                            external HTTP proxy to tunnel the outgoing HTTP traffic. This parameter
                            is only applicable to the HTTP sender. HTTPS sender does not support
                            external proxies yet.
                            <div class="xmlConf">&lt;parameter name="http.proxyHost"&gt;proxy.example.com&lt;/parameter&gt;</div>
                        </td>
                        <td>No</td>
                        <td>N/A</td>
                    </tr>
                    <tr>
                        <td>http.proxyPort</td>
                        <td>
                            The port number of the proxy server through which the HTTP messages
                            should be sent. Only used if the http.proxyHost parameter is also
                            configured. This parameter is only applicable to the HTTP sender.
                            HTTPS sender does not support external proxies yet.
                            <div class="xmlConf">&lt;parameter name="http.proxyPort"&gt;8080&lt;/parameter&gt;</div>
                        </td>
                        <td>No</td>
                        <td>80</td>
                    </tr>
                    <tr>
                        <td>http.nonProxyHosts</td>
                        <td>
                            Use this parameter to specify a proxy bypass list. That is, a list of
                            target hosts for which Synapse will not use the configured external
                            proxy. Only used if the http.proxyHost parameter is also set. The value
                            of this parameter can be a single hostname/IP address or a list of
                            hostnames/IP addresses separated by the '|' character. Parameter also
                            supports regular expressions which can be used to specify hostname
                            patterns.
                            <div class="xmlConf">&lt;parameter name="http.nonProxyHosts"&gt;10.0.0.8|foo.com|*.bar.org&lt;/parameter&gt;</div>
                        </td>
                        <td>No</td>
                        <td>N/A</td>
                    </tr>
                </table>
                <p><a href="#Contents">[Back to top]</a></p>
            </subsection>
            <subsection name="HTTPS Transport Listener" id="HTTPSListener">
                <p>
                    Pass Through HTTPS listener supports all the parameters supported by the
                    HTTP listener. In addition, HTTPS listener supports several SSL/TLS specific
                    parameters. The default HTTPS listener configuration in the axis2.xml file is
                    shown below.
                </p>
                <div class="xmlConf">&lt;transportReceiver name="https" class="org.apache.synapse.transport.passthru.PassThroughHttpSSLListener"&gt;
    &lt;parameter name="port" locked="false"&gt;8243&lt;/parameter&gt;
    &lt;parameter name="httpGetProcessor" locked="false"&gt;org.apache.synapse.transport.passthru.api.PassThroughNHttpGetProcessor&lt;/parameter&gt;
    &lt;parameter name="keystore" locked="false"&gt;
        &lt;KeyStore&gt;
            &lt;Location&gt;lib/identity.jks&lt;/Location&gt;
            &lt;Type&gt;JKS&lt;/Type&gt;
            &lt;Password&gt;password&lt;/Password&gt;
            &lt;KeyPassword&gt;password&lt;/KeyPassword&gt;
        &lt;/KeyStore&gt;
    &lt;/parameter&gt;
    &lt;parameter name="truststore" locked="false"&gt;
        &lt;TrustStore&gt;
            &lt;Location&gt;lib/trust.jks&lt;/Location&gt;
            &lt;Type&gt;JKS&lt;/Type&gt;
            &lt;Password&gt;password&lt;/Password&gt;
        &lt;/TrustStore&gt;
    &lt;/parameter&gt;
&lt;/transportReceiver&gt;</div>
                <p>
                    A complete list of parameters supported by the HTTPS listener is given below.
                    Information regarding the parameters also supported by the HTTP listener are
                    duplicated here for reader's convenience.
                </p>
                <table>
                    <tr>
                        <th>Parameter Name</th>
                        <th>Description/Example</th>
                        <th>Required</th>
                        <th>Default</th>
                    </tr>
                    <tr>
                        <td>port</td>
                        <td>
                            The port number on which the HTTPS listener should listen.
                            <div class="xmlConf">&lt;parameter name="port"&gt;8243&lt;/parameter&gt;</div>
                        </td>
                        <td>Yes</td>
                        <td>N/A</td>
                    </tr>
                    <tr>
                        <td>keystore</td>
                        <td>
                            Specifies the keystore that should be used to initialize SSL/TLS
                            support. A keystore typically houses a private key and some certificates
                            with their corresponding public keys. The value of this parameter is a
                            complex XML element. This XML element should specify:
                            <ul>
                                <li>Location: Path to the keystore file</li>
                                <li>Type: type of the keystore file (JKS, PKCS etc.)</li>
                                <li>Password: Password to unlock the keystore file</li>
                                <li>KeyPassword: Password to unlock the private key in the keystore file</li>
                            </ul>
                            All 4 values are required. Keystore paths are resolved relative to the
                            Synapse installation (SYNAPSE_HOME) directory. If you are not familiar with
                            Java security and keystores, please refer
                            <a href="http://docs.oracle.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html">Java Cryptography Architecture</a>
                            specification.
                            <br/>
                            <br/>
                            <strong>
                                Synapse ships with a default keystore file. It is highly recommended
                                that a different keystore file is used in production deployments of
                                Synapse, since the passwords of the default keystore are publicly
                                known.
                            </strong>
                            <div class="xmlConf">&lt;parameter name="keystore" locked="false"&gt;
    &lt;KeyStore&gt;
        &lt;Location&gt;lib/identity.jks&lt;/Location&gt;
        &lt;Type&gt;JKS&lt;/Type&gt;
        &lt;Password&gt;password&lt;/Password&gt;
        &lt;KeyPassword&gt;password&lt;/KeyPassword&gt;
    &lt;/KeyStore&gt;
&lt;/parameter&gt;</div>
                        </td>
                        <td>No</td>
                        <td>N/A</td>
                    </tr>
                    <tr>
                        <td>truststore</td>
                        <td>
                            Specifies the truststore that should be used to initialize SSL/TLS
                            support. A truststore typically houses the CA certificates and other
                            trusted public certificates. The value of this parameter is a complex
                            XML element. This XML element should specify:
                            <ul>
                                <li>Location: Path to the truststore file</li>
                                <li>Type: type of the truststore file (JKS, PKCS etc.)</li>
                                <li>Password: Password to unlock the truststore file</li>
                            </ul>
                            All 3 values are required. Truststore paths are resolved relative to the
                            Synapse installation (SYNAPSE_HOME) directory. If you are not familiar with
                            Java security and truststores, please refer
                            <a href="http://docs.oracle.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html">Java Cryptography Architecture</a>
                            specification.
                            <br/>
                            <br/>
                            <strong>
                                Synapse ships with a default truststore file. It is highly recommended
                                that a different truststore file is used in production deployments of
                                Synapse, since the password of the default truststore is publicly
                                known.
                            </strong>
                            <div class="xmlConf">&lt;parameter name="truststore" locked="false"&gt;
    &lt;TrustStore&gt;
        &lt;Location&gt;lib/trust.jks&lt;/Location&gt;
        &lt;Type&gt;JKS&lt;/Type&gt;
        &lt;Password&gt;password&lt;/Password&gt;
    &lt;/TrustStore&gt;
&lt;/parameter&gt;</div>
                        </td>
                        <td>No</td>
                        <td>N/A</td>
                    </tr>
                    <tr>
                        <td>SSLVerifyClient</td>
                        <td>
                            Use this parameter to enable client certificate verification (client
                            authentication). This option provides functionality similar to the
                            <a href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslverifyclient">SSLVerifyClient directive</a>
                            of Apache HTTPD. Supported values are:
                            <ul>
                                <li>none: No client certificate is required</li>
                                <li>optional: Client may present a valid certificate, but is not required to do so</li>
                                <li>require: Client must present a valid certificate (the SSL handshake will not succeed without it)</li>
                            </ul>
                            <div class="xmlConf">&lt;parameter name="SSLVerifyClient"&gt;require&lt;/parameter&gt;</div>
                        </td>
                        <td>No</td>
                        <td>None</td>
                    </tr>
                    <tr>
                        <td>bind-address</td>
                        <td>
                            The hostname or IP address to which the HTTP listener should bind. When
                            deploying Synapse on machines that have multiple network interfaces,
                            this parameter can be used to bind the HTTP listener to a specific network
                            interface.
                            <div class="xmlConf">&lt;parameter name="bind-address"&gt;10.0.0.5&lt;/parameter&gt;</div>
                        </td>
                        <td>No</td>
                        <td>All available network interfaces</td>
                    </tr>
                    <tr>
                        <td>hostname</td>
                        <td>
                            The hostname or IP address used to calculate the service endpoints
                            exposed through this transport listener. This can be used to customize
                            the hostname of the endpoints (EPRs) that appear in the generated WSDLs.
                            This parameter is ignored if the WSDLEPRPrefix parameter is set.
                            <div class="xmlConf">&lt;parameter name="hostname"&gt;10.0.0.5&lt;/parameter&gt;</div>
                        </td>
                        <td>No</td>
                        <td>localhost</td>
                    </tr>
                    <tr>
                        <td>httpGetProcessor</td>
                        <td>
                            The full qualified name of the class that's responsible for handling incoming
                            HTTP GET requests. The specified class must implement the
                            org.apache.synapse.transport.passthru.HttpGetRequestProcessor interface. If it
                            is required to customize the way Synapse handles HTTP GET requests, one could
                            implement the above interface, and register the custom class with Synapse using
                            this parameter. By default Synapse ships with an HTTP GET request handler that
                            responds to ?wsdl and ?xsd requests and mediates all the others.
                            <div class="xmlConf">&lt;parameter name="httpGetProcessor"&gt;foo.bar.CustomGETProcessor&lt;/parameter&gt;</div>
                        </td>
                        <td>No</td>
                        <td>N/A</td>
                    </tr>
                    <tr>
                        <td>WSDLEPRPrefix</td>
                        <td>
                            A URL prefix that should be added to all the HTTP endpoints exposed
                            through this transport listener. This prefix will appear in all WSDLs
                            advertised by the transport. This is particularly useful when Synapse
                            is fronted by a proxy server or a load balancer and it is required to mention
                            the proxy/load balancer endpoints in the WSDLs generated by Synapse. This
                            parameter has higher priority than the hostname parameter.
                            <div class="xmlConf">&lt;parameter name="WSDLEPRPrefix"&gt;https://proxy.example.com:8443/&lt;/parameter&gt;</div>
                        </td>
                        <td>No</td>
                        <td>https://&lt;host&gt;:&lt;port&gt;/</td>
                    </tr>
                </table>
                <p><a href="#Contents">[Back to top]</a></p>
            </subsection>
            <subsection name="HTTPS Transport Sender" id="HTTPSSender">
                <p>
                    As of today, the Pass Through HTTPS sender does not support sending messages
                    through an external proxy. Therefore some of the parameters supported by the
                    HTTP sender (http.proxyHost, http.proxyPort etc.) cannot be used with the
                    HTTPS sender. However, there are several SSL/TLS related parameters that need
                    to be configured when setting up the HTTPS sender. The default HTTPS sender
                    configuration in the axis2.xml file is shown below.
                </p>
                <div class="xmlConf">&lt;transportSender name="https" class="org.apache.synapse.transport.passthru.PassThroughHttpSSLSender"&gt;
    &lt;parameter name="keystore" locked="false"&gt;
        &lt;KeyStore&gt;
            &lt;Location&gt;lib/identity.jks&lt;/Location&gt;
            &lt;Type&gt;JKS&lt;/Type&gt;
            &lt;Password&gt;password&lt;/Password&gt;
            &lt;KeyPassword&gt;password&lt;/KeyPassword&gt;
        &lt;/KeyStore&gt;
    &lt;/parameter&gt;
    &lt;parameter name="truststore" locked="false"&gt;
        &lt;TrustStore&gt;
            &lt;Location&gt;lib/trust.jks&lt;/Location&gt;
            &lt;Type&gt;JKS&lt;/Type&gt;
            &lt;Password&gt;password&lt;/Password&gt;
        &lt;/TrustStore&gt;
    &lt;/parameter&gt;
&lt;/transportSender&gt;</div>
                <p>
                    Following table lists all the parameters supported by the Pass Through HTTPS
                    sender.
                </p>
                <table>
                    <tr>
                        <th>Parameter Name</th>
                        <th>Description/Example</th>
                        <th>Required</th>
                        <th>Default</th>
                    </tr>
                    <tr>
                        <td>keystore</td>
                        <td>
                            Specifies the keystore that should be used to initialize SSL/TLS
                            support. A keystore typically houses a private key and some certificates
                            with their corresponding public keys. The value of this parameter is a
                            complex XML element. This XML element should specify:
                            <ul>
                                <li>Location: Path to the keystore file</li>
                                <li>Type: type of the keystore file (JKS, PKCS etc.)</li>
                                <li>Password: Password to unlock the keystore file</li>
                                <li>KeyPassword: Password to unlock the private key in the keystore file</li>
                            </ul>
                            All 4 values are required. Keystore paths are resolved relative to the
                            Synapse installation (SYNAPSE_HOME) directory. If you are not familiar with
                            Java security and keystores, please refer
                            <a href="http://docs.oracle.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html">Java Cryptography Architecture</a>
                            specification.
                            <br/>
                            <br/>
                            <strong>
                                Synapse ships with a default keystore file. It is highly recommended
                                that a different keystore file is used in production deployments of
                                Synapse, since the passwords of the default keystore are publicly
                                known.
                            </strong>
                            <div class="xmlConf">&lt;parameter name="keystore" locked="false"&gt;
    &lt;KeyStore&gt;
        &lt;Location&gt;lib/identity.jks&lt;/Location&gt;
        &lt;Type&gt;JKS&lt;/Type&gt;
        &lt;Password&gt;password&lt;/Password&gt;
        &lt;KeyPassword&gt;password&lt;/KeyPassword&gt;
    &lt;/KeyStore&gt;
&lt;/parameter&gt;</div>
                        </td>
                        <td>No</td>
                        <td>N/A</td>
                    </tr>
                    <tr>
                        <td>truststore</td>
                        <td>
                            Specifies the truststore that should be used to initialize SSL/TLS
                            support. A truststore typically houses the CA certificates and other
                            trusted public certificates. The value of this parameter is a complex
                            XML element. This XML element should specify:
                            <ul>
                                <li>Location: Path to the truststore file</li>
                                <li>Type: type of the truststore file (JKS, PKCS etc.)</li>
                                <li>Password: Password to unlock the truststore file</li>
                            </ul>
                            All 3 values are required. Truststore paths are resolved relative to the
                            Synapse installation (SYNAPSE_HOME) directory. If you are not familiar with
                            Java security and truststores, please refer
                            <a href="http://docs.oracle.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html">Java Cryptography Architecture</a>
                            specification.
                            <br/>
                            <br/>
                            <strong>
                                Synapse ships with a default truststore file. It is highly recommended
                                that a different truststore file is used in production deployments of
                                Synapse, since the password of the default truststore is publicly
                                known.
                            </strong>
                            <div class="xmlConf">&lt;parameter name="truststore" locked="false"&gt;
    &lt;TrustStore&gt;
        &lt;Location&gt;lib/trust.jks&lt;/Location&gt;
        &lt;Type&gt;JKS&lt;/Type&gt;
        &lt;Password&gt;password&lt;/Password&gt;
    &lt;/TrustStore&gt;
&lt;/parameter&gt;</div>
                        </td>
                        <td>No</td>
                        <td>N/A</td>
                    </tr>
                    <tr>
                        <td>HostnameVerifier</td>
                        <td>
                            This parameter can be used to configure target hostname verification.
                            That is, it enables validating server hostnames against the names specified
                            in the certificates presented by the servers during SSL handshake.
                            Supported values are:
                            <ul>
                                <li>Default</li>
                                <li>DefaultAndLocalhost</li>
                                <li>AllowAll</li>
                                <li>Strict</li>
                            </ul>
                            Please refer <a href="http://synapse.apache.org/apidocs/org/apache/synapse/transport/nhttp/HostnameVerifier.html">HostnameVerifier</a>
                            Javadocs to learn more about this feature and the semantics of the above
                            options. The AllowAll option essentially disables hostname verification
                            by accepting all certificates. The Strict option requires the server
                            hostnames to match exactly to the names specified in the server certificates.
                            Any deviations will cause the SSL handshake to fail.
                            <div class="xmlConf">&lt;parameter name="HostnameVerifier"&gt;Strict&lt;/parameter&gt;</div>
                        </td>
                        <td>No</td>
                        <td>Default</td>
                    </tr>
                    <tr>
                        <td>novalidatecert</td>
                        <td>
                            Use this parameter to turn on/off server certificate validation. If set to
                            'true', the HTTPS sender will not attempt to validate the certificates
                            presented by the remote servers. This behavior, however, is not recommended
                            for production deployments due to the potential security risks. If the
                            truststore parameter is specified, the value of this parameter is ignored
                            altogether.
                            <div class="xmlConf">&lt;parameter name="novalidatecert"&gt;true&lt;/parameter&gt;</div>
                        </td>
                        <td>No</td>
                        <td>false</td>
                    </tr>
                    <tr>
                        <td>customSSLProfiles</td>
                        <td>
                            By default, the HTTPS sender uses the SSL settings configured under
                            keystore and truststore parameters to communicate with all remote
                            HTTPS endpoints. However, in some cases we may need to use different
                            SSL settings to communicate with different endpoints. The customSSLProfiles
                            parameter allows configuring separate keystores and truststores for
                            each destination server. The value of this parameter is a set of XML elements
                            (profile elements). Each profile element must be configured with the following
                            child elements:
                            <ul>
                                <li>servers: A comma-separated list of servers to which this SSL profile is related to</li>
                                <li>KeyStore: A keystore configuration (similar to the keystore parameter)</li>
                                <li>TrustStore: A truststore configuration (similar to the truststore parameter)</li>
                                <li>novalidatecert: Optional element to disable certification validation (can be set to true or false)</li>
                            </ul>
                            An example is given below. According to this configuration, when Synapse
                            communicates with server1.example.com or server2.example.com, it will use
                            the first SSL configuration (identity1.jks and trust1.jks). When
                            communicating with server3.example.com, it will use the second SSL
                            configuration (identity2.jks and trust2.jks). For all other endpoints,
                            Synapse will use the default SSL configuration, configured under keystore
                            and truststore parameters.
                            <div class="xmlConf">&lt;parameter name="customSSLProfiles"&gt;
    &lt;profile&gt;
        &lt;servers&gt;server1.example.com:443,server2.example.com:443&lt;/servers&gt;
        &lt;KeyStore&gt;
            &lt;Location&gt;lib/identity1.jks&lt;/Location&gt;
            &lt;Type&gt;JKS&lt;/Type&gt;
            &lt;Password&gt;password&lt;/Password&gt;
            &lt;KeyPassword&gt;password&lt;/KeyPassword&gt;
        &lt;/KeyStore&gt;
        &lt;TrustStore&gt;
            &lt;Location&gt;lib/trust1.jks&lt;/Location&gt;
            &lt;Type&gt;JKS&lt;/Type&gt;
            &lt;Password&gt;password&lt;/Password&gt;
        &lt;/TrustStore&gt;
    &lt;/profile&gt;
    &lt;profile&gt;
        &lt;servers&gt;server3.example.com:443&lt;/servers&gt;
        &lt;KeyStore&gt;
            &lt;Location&gt;lib/identity2.jks&lt;/Location&gt;
            &lt;Type&gt;JKS&lt;/Type&gt;
            &lt;Password&gt;password&lt;/Password&gt;
            &lt;KeyPassword&gt;password&lt;/KeyPassword&gt;
        &lt;/KeyStore&gt;
        &lt;TrustStore&gt;
            &lt;Location&gt;lib/trust2.jks&lt;/Location&gt;
            &lt;Type&gt;JKS&lt;/Type&gt;
            &lt;Password&gt;password&lt;/Password&gt;
        &lt;/TrustStore&gt;
    &lt;/profile&gt;
&lt;/parameter&gt;</div>
                        </td>
                        <td>No</td>
                        <td>N/A</td>
                    </tr>
                    <tr>
                        <td>CertificateRevocationVerifier</td>
                        <td>
                            Enable revocation status validation of server certificates using
                            <a href="http://www.ietf.org/rfc/rfc2560.txt">OCSP</a> and
                            <a href="http://www.ietf.org/rfc/rfc5280.txt">CRL</a>. Simply uncommenting
                            this parameter under the HTTPS sender configuration will activate the
                            feature. Two LRU caches are used to cache CRLs and OCSP responses until
                            they are expired. Two child XML elements are used to configure the cache
                            behavior.
                            <ul>
                                <li>
                                    CacheSize: Controls the maximum size of each cache. When this
                                    limit is reached, the old values will be automatically removed
                                    and updated with new values. Default value is 50.
                                </li>
                                <li>
                                    CacheDurationMins: Sets the time duration (in minutes) between
                                    two consecutive runs of the CacheManager task which periodically
                                    performs housekeeping work in each cache. Default value is 15.
                                </li>
                            </ul>
                            <div class="xmlConf">&lt;parameter name="CertificateRevocationVerifier" locked="false"&gt;
    &lt;CacheSize&gt;100&lt;/CacheSize&gt;
    &lt;CacheDurationMins&gt;&lt;/CacheDurationMins&gt;
&lt;/parameter&gt;</div>
                        </td>
                        <td>No</td>
                        <td>N/A</td>
                    </tr>
                </table>
                <p><a href="#Contents">[Back to top]</a></p>
            </subsection>
        </section>
        <section name="Advanced Settings and Performance Tuning" id="AdvancedSettings">
            <p>
                In addition to the basic parameters described in the previous section, the
                Pass Through HTTP transport provides some advanced options to tweak its
                runtime behavior and performance. These options should be configured in the
                <strong>SYNAPSE_HOME/lib/passthru-http.properties</strong> 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>
            <subsection name="Apache HTTP Core Settings" id="HttpCoreSettings">
                <p>
                    Following properties control various facets of
                    <a href="http://hc.apache.org/httpcomponents-core-ga/index.html">Apache HTTP Core</a>,
                    the framework underlying the Pass Through HTTP transport.
                </p>
                <table>
                    <tr>
                        <th>Parameter Name</th>
                        <th>Description/Example</th>
                        <th>Required</th>
                        <th>Default</th>
                    </tr>
                    <tr>
                        <td>http.socket.timeout <a name="http.socket.timeout"/></td>
                        <td>
                            Sets the TCP socket timeout in milliseconds
                            (See <a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/net/SocketOptions.html#SO_TIMEOUT">SO_TIMEOUT</a>).
                            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>
                        <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>
                        <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>
                        <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>
                        <td>http.nio.interest-ops-queueing</td>
                        <td>
                            Determines whether or not I/O interest operations are to be queued and
                            executed asynchronously by the I/O reactor thread or to be applied to
                            the underlying
                            <a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/nio/channels/SelectionKey.html">SelectionKey</a>
                            immediately. Allowed values are either 'true' or 'false'.
                            <div class="xmlConf">http.nio.interest-ops-queueing=false</div>
                        </td>
                        <td>No</td>
                        <td>false</td>
                    </tr>
                    <tr>
                        <td>http.tcp.nodelay</td>
                        <td>
                            Setting this property to 'true' disables
                            <a href="http://en.wikipedia.org/wiki/Nagle's_algorithm">Nagle's algorithm</a>
                            for the HTTP connections. That is, outgoing data will not be buffered
                            and aggregated together
                            (See <a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/net/SocketOptions.html#TCP_NODELAY">TCP_NODELAY</a>).
                            <div class="xmlConf">http.tcp.nodelay=true</div>
                        </td>
                        <td>No</td>
                        <td>true</td>
                    </tr>
                    <tr>
                        <td>http.socket.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>
                        <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 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>
                        <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 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>
                        <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 href="http://docs.oracle.com/javase/1.5.0/docs/api/java/net/SocketOptions.html#SO_LINGER">SO_LINGER</a>).
                            <div class="xmlConf">http.socket.linger=5000</div>
                        </td>
                        <td>No</td>
                        <td>-1</td>
                    </tr>
                    <tr>
                        <td>http.socket.reuseaddr</td>
                        <td>
                            Sets the <a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/net/SocketOptions.html#SO_REUSEADDR">SO_REUSEADDR</a>
                            socket option for the sockets created by the HTTP transport. Accepted
                            values are either 'true' or 'false'.
                            <div class="xmlConf">http.socket.reuseaddr=true</div>
                        </td>
                        <td>No</td>
                        <td>false</td>
                    </tr>
                    <tr>
                        <td>http.nio.select-interval</td>
                        <td>
                            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>
                        <td>io_threads_per_reactor <a name="io_threads_per_reactor"/></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>
                        <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 href="http://docs.oracle.com/javase/1.5.0/docs/api/java/nio/charset/CodingErrorAction.html">CodingErrorAction</a>
                            for more details on each of these options.
                            <div class="xmlConf">http.malformed.input.action=ignore</div>
                        </td>
                        <td>No</td>
                        <td>report</td>
                    </tr>
                    <tr>
                        <td>http.unmappable.input.action</td>
                        <td>
                            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 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>
            </subsection>
            <subsection name="Synapse HTTP Mediation Settings" id="SynapseSettings">
                <p>
                    Following settings determine the behavior of Synapse with respect to mediating
                    HTTP traffic.
                </p>
                <table>
                    <tr>
                        <th>Parameter Name</th>
                        <th>Description/Example</th>
                        <th>Required</th>
                        <th>Default</th>
                    </tr>
                    <tr>
                        <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>
                        <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 href="http://docs.oracle.com/javase/6/docs/api/java/lang/Integer.html#MAX_VALUE">Integer.MAX_VALUE</a></td>
                    </tr>
                    <tr>
                        <td>http.user.agent.value <a name="http.user.agent.value"/></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>
                        <td>http.server.value <a name="http.server.value"/></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>
                        <td>http.user.agent.preserve <a name="http.user.agent.preserve"/></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>
                        <td>http.server.preserve <a name="http.server.preserve"/></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>
            </subsection>
            <subsection name="Thread Pool Settings" id="ThreadPoolSettings">
                <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>
                    <tr>
                        <th>Parameter Name</th>
                        <th>Description/Example</th>
                        <th>Required</th>
                        <th>Default</th>
                    </tr>
                    <tr>
                        <td>worker_pool_size_core <a name="worker_pool_size_core"/></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>
                        <td>worker_pool_size_max <a name="worker_pool_size_max"/></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>
                        <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>
                        <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>
            </subsection>
            <subsection name="Guidelines for Using Advanced Settings" id="AdvancedGuidelines">
                <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>
            </subsection>
            <subsection name="Unix/Linux Specific Settings" id="LinuxSettings">
                <p>
                    Users deploying Synapse on Unix/Linux systems are further advised to set the
                    following OS level configuration parameters. This is completely optional, but
                    for high-throughput and high-volume deployments, configuring these parameters
                    may 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>
            </subsection>
        </section>
        <section name="Logging Configuration" id="Logging">
            <p>
                <strong>Note: This section is applicable to both Pass Through and NHTTP transports of
                Synapse.</strong>
            </p>
            <p>
                Synapse HTTP transports have some advanced logging capabilities built in to them,
                which can be enabled to obtain more low-level information about how the transports
                operate. These logging features are based on
                <a href="http://commons.apache.org/proper/commons-logging/">Apache Commons Logging</a>
                and Log4J, which constitute the logging framework used by Apache Synapse. Therefore,
                these features should be enabled from the <strong>SYNAPSE_HOME/lib/log4j.properties</strong>
                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>
            <subsection name="Guidelines for Using Advanced Logging" id="LoggingGuidelines">
                <p>
                    Most of the above advanced logging features have been designed to aid Synapse developers
                    in identifying problems and fixing issues in the Synapse HTTP transports. However,
                    they are also useful to the Synapse users and system administrators when debugging
                    configuration errors and certain types of integration problems. For instance, if you
                    ever come across a situation where Synapse behaves erratically when communicating
                    with a particular client or a server, enabling some of the above mentioned logging
                    features may help you pinpoint the cause of the issue.
                </p>
                <p>
                    Please bare in mind that you trade mediation performance for additional logging.
                    As you enable more and more logging features, the performance degradation induced
                    by logging becomes greater. Hence these advanced logging features are not suitable
                    to be enabled on production deployments. However, they are quite helpful during the
                    development and testing phases of an integration project. In a production deployment,
                    you may occasionally need to enable advanced logging for short periods of time to obtain
                    debug information to resolve certain production issues. But it is not recommended to
                    have these features permanently enabled on production systems.
                </p>
                <p>
                    Also note that activating advanced logging features may greatly increase the amount
                    of data written to the Synapse log files. If the Synapse server is receiving a large
                    volume of traffic, enabling any one of the above logging features may cause
                    Synapse to generate gigabytes of logs within minutes. This could easily drive a
                    system out of disk space or cause some other unexpected I/O issue. Therefore be
                    mindful about how much extra information you want Synapse to log, the prevailing
                    levels of load/traffic and the availability of hardware resources.
                </p>
                <p><a href="#Contents">[Back to top]</a></p>
            </subsection>
        </section>
        <section name="Monitoring with JMX" id="JMX">
            <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
                by Synapse when forwarding HTTP traffic. Following sections describe the available
                JMX MBeans and the attributes present in each MBean.
            </p>
            <subsection name="ConnectionsView (org.apache.synapse.PassThroughConnections)" id="ConnectionsView">
                <p>
                    Typically, Synapse exposes four instances of this MBean, under the following
                    identifiers.
                </p>
                <ul>
                    <li>
                        http-listener: Provides information regarding the connections established
                        between the client applications and the Pass Through HTTP listener.
                    </li>
                    <li>
                        http-sender: Provides information regarding the connections established
                        between the Pass Through HTTP sender and the backend servers.
                    </li>
                    <li>
                        https-listener: Provides information regarding the connections established
                        between the client applications and the Pass Through HTTPS listener.
                    </li>
                    <li>
                        https-sender: Provides information regarding the connections established
                        between the Pass Through HTTPS sender and the backend servers.
                    </li>
                </ul>
                <p>
                    Each instance of the MBean consists of the following attributes.
                </p>
                <table>
                    <tr>
                        <th>Attribute</th>
                        <th>Data Type</th>
                        <th>Description</th>
                    </tr>
                    <tr>
                        <td>ActiveConnections</td>
                        <td>int</td>
                        <td>
                            Number of currently active (open) connections
                        </td>
                    </tr>
                    <tr>
                        <td>LastMinuteConnections</td>
                        <td>int</td>
                        <td>
                            Number of connections created during last minute (updated every minute)
                        </td>
                    </tr>
                    <tr>
                        <td>Last5MinuteConnections</td>
                        <td>int</td>
                        <td>
                            Number of connections created during last 5 minutes (updated every minute)
                        </td>
                    </tr>
                    <tr>
                        <td>Last15MinuteConnections</td>
                        <td>int</td>
                        <td>
                            Number of connections created during last 15 minutes (updated every minute)
                        </td>
                    </tr>
                    <tr>
                        <td>LastHourConnections</td>
                        <td>int</td>
                        <td>
                            Number of connections created during last hour (updated every 5 minutes)
                        </td>
                    </tr>
                    <tr>
                        <td>Last8HourConnections</td>
                        <td>int</td>
                        <td>
                            Number of connections created during last 8 hours (updated every 5 minutes)
                        </td>
                    </tr>
                    <tr>
                        <td>Last24HourConnections</td>
                        <td>int</td>
                        <td>
                            Number of connections created during last 24 hours (updated every 5 minutes)
                        </td>
                    </tr>
                    <tr>
                        <td>RequestSizeMap</td>
                        <td>java.util.Map</td>
                        <td>
                            A map representing the size distribution of the request messages
                            processed by the transport. Map keys are strings and the values are
                            integers. Following keys are available by default.
                            <ul>
                                <li>&lt; 1 K</li>
                                <li>&lt; 10 K</li>
                                <li>&lt; 100 K</li>
                                <li>&lt; 1 M</li>
                                <li>&lt; 10 M</li>
                                <li>&gt; 10 M</li>
                            </ul>
                        </td>
                    </tr>
                    <tr>
                        <td>ResponseSizeMap</td>
                        <td>java.util.Map</td>
                        <td>
                            A map representing the size distribution of the response messages
                            processed by the transport. Map keys are strings and the values are
                            integers. Following keys are available by default.
                            <ul>
                                <li>&lt; 1 K</li>
                                <li>&lt; 10 K</li>
                                <li>&lt; 100 K</li>
                                <li>&lt; 1 M</li>
                                <li>&lt; 10 M</li>
                                <li>&gt; 10 M</li>
                            </ul>
                        </td>
                    </tr>
                    <tr>
                        <td>LastResetTime</td>
                        <td>java.util.Date</td>
                        <td>
                            The MBean statistics can be reset manually via one of the operations
                            provided in the MBean interface. This attribute keeps track of the date
                            and time of the last reset event. If the MBean has never been reset,
                            this attribute provides the time when the transport was started.
                        </td>
                    </tr>
                </table>
                <p><a href="#Contents">[Back to top]</a></p>
            </subsection>
            <subsection name="LatencyView (org.apache.synapse.PassThroughTransportLatency)" id="LatencyView">
                <p>
                    Synapse keeps track of how much latency (delay) is added by the ESB to each
                    message flow. This is an estimate of how much time a client application would
                    save if the requests were to go directly to the backend server, instead of
                    going through Synapse. The LatencyView MBean exposes this information via JMX.
                    Synapse usually exposes two instances of this MBean, one for the HTTP transport
                    and the other for the HTTPS transport. Each instance consists of the following
                    attributes.
                </p>
                <table>
                    <tr>
                        <th>Attribute</th>
                        <th>Data Type</th>
                        <th>Description</th>
                    </tr>
                    <tr>
                        <td>AllTimeAvgLatency</td>
                        <td>double</td>
                        <td>
                            Average latency in milliseconds, computed over all the messages mediated
                            by the transport
                        </td>
                    </tr>
                    <tr>
                        <td>LastMinuteAvgLatency</td>
                        <td>double</td>
                        <td>
                            Average latency in milliseconds, computed over the messages mediated
                            by the transport during last minute (updated every minute)
                        </td>
                    </tr>
                    <tr>
                        <td>Last5MinuteAvgLatency</td>
                        <td>double</td>
                        <td>
                            Average latency in milliseconds, computed over the messages mediated
                            by the transport during last 5 minutes (updated every minute)
                        </td>
                    </tr>
                    <tr>
                        <td>Last15MinuteAvgLatency</td>
                        <td>double</td>
                        <td>
                            Average latency in milliseconds, computed over the messages mediated
                            by the transport during last 15 minutes (updated every minute)
                        </td>
                    </tr>
                    <tr>
                        <td>LastHourAvgLatency</td>
                        <td>double</td>
                        <td>
                            Average latency in milliseconds, computed over the messages mediated
                            by the transport during last hour (updated every 5 minutes)
                        </td>
                    </tr>
                    <tr>
                        <td>Last8HourAvgLatency</td>
                        <td>double</td>
                        <td>
                            Average latency in milliseconds, computed over the messages mediated
                            by the transport during last 8 hours (updated every 5 minutes)
                        </td>
                    </tr>
                    <tr>
                        <td>Last24HourAvgLatency</td>
                        <td>double</td>
                        <td>
                            Average latency in milliseconds, computed over the messages mediated
                            by the transport during last 24 hours (updated every 5 minutes)
                        </td>
                    </tr>
                    <tr>
                        <td>LastResetTime</td>
                        <td>java.util.Date</td>
                        <td>
                            The MBean statistics can be reset manually via one of the operations
                            provided in the MBean interface. This attribute keeps track of the date
                            and time of the last reset event. If the MBean has never been reset,
                            this attribute provides the time when the transport was started.
                        </td>
                    </tr>
                </table>
                <p><a href="#Contents">[Back to top]</a></p>
            </subsection>
            <subsection name="TransportView (org.apache.synapse.Transport)" id="TransportView">
                <p>
                    An instance of this MBean is usually available for each transport listener
                    and sender enabled in Synapse. This also includes non-HTTP transports. As far
                    as the Pass Through HTTP transport is concerned, Synapse exposes four instances
                    of this MBean with the following identifiers.
                </p>
                <ul>
                    <li>passthru-http-receiver</li>
                    <li>passthru-http-sender</li>
                    <li>passthru-https-receiver</li>
                    <li>passthru-https-sender</li>
                </ul>
                <p>
                    Following attributes are available on each instance of the MBean.
                </p>
                <table>
                    <tr>
                        <th>Attribute</th>
                        <th>Data Type</th>
                        <th>Description</th>
                    </tr>
                    <tr>
                        <td>ActiveThreadCount</td>
                        <td>int</td>
                        <td>
                            The number of threads in the transport thread pool, that are currently
                            executing tasks
                        </td>
                    </tr>
                    <tr>
                        <td>AvgSizeReceived</td>
                        <td>double</td>
                        <td>
                            Average size (in bytes) of all the messages received
                        </td>
                    </tr>
                    <tr>
                        <td>AvgSizeSent</td>
                        <td>int</td>
                        <td>
                            Average size (in bytes) of all the messages sent
                        </td>
                    </tr>
                    <tr>
                        <td>BytesReceived</td>
                        <td>long</td>
                        <td>
                            The total number of bytes received by the transport
                        </td>
                    </tr>
                    <tr>
                        <td>BytesSent</td>
                        <td>long</td>
                        <td>
                            The total number of bytes sent by the transport
                        </td>
                    </tr>
                    <tr>
                        <td>FaultsReceiving</td>
                        <td>long</td>
                        <td>
                            The total number of errors encountered while receiving messages
                        </td>
                    </tr>
                    <tr>
                        <td>FaultsSent</td>
                        <td>long</td>
                        <td>
                            The total number of errors encountered while sending messages
                        </td>
                    </tr>
                    <tr>
                        <td>LastResetTime</td>
                        <td>long</td>
                        <td>
                            The MBean statistics can be reset manually via one of the operations
                            provided in the MBean interface. This attribute keeps track of the
                            timestamp (milliseconds since epoch) of the last reset event. If the
                            MBean has never been reset, this attribute provides the time when the
                            transport was started.
                        </td>
                    </tr>
                    <tr>
                        <td>MaxSizeReceived</td>
                        <td>long</td>
                        <td>
                            Size of the largest message received (in bytes)
                        </td>
                    </tr>
                    <tr>
                        <td>MaxSizeSent</td>
                        <td>long</td>
                        <td>
                            Size of the largest message sent (int bytes)
                        </td>
                    </tr>
                    <tr>
                        <td>MessagesReceived</td>
                        <td>long</td>
                        <td>
                            Total number of messages received
                        </td>
                    </tr>
                    <tr>
                        <td>MessagesSent</td>
                        <td>long</td>
                        <td>
                            Total number of messages sent
                        </td>
                    </tr>
                    <tr>
                        <td>MetricsWindow</td>
                        <td>long</td>
                        <td>
                            Time elapsed in milliseconds, since the last MBean reset event
                        </td>
                    </tr>
                    <tr>
                        <td>MinSizeReceived</td>
                        <td>long</td>
                        <td>
                            Size of the smallest message received (in bytes)
                        </td>
                    </tr>
                    <tr>
                        <td>MinSizeSent</td>
                        <td>long</td>
                        <td>
                            Size of the smallest message sent (int bytes)
                        </td>
                    </tr>
                    <tr>
                        <td>QueueSize</td>
                        <td>long</td>
                        <td>
                            Number of tasks currently queued on the transport thread pool
                        </td>
                    </tr>
                    <tr>
                        <td>ResponseCodeTable</td>
                        <td>java.util.Map</td>
                        <td>
                            A map representing the distribution of HTTP status codes received
                            by the transport. Keys are integers (status codes) and the values are
                            long integers indicating the number of time each status code was encountered.
                        </td>
                    </tr>
                    <tr>
                        <td>TimeoutsReceiving</td>
                        <td>long</td>
                        <td>
                            Number of timeouts encountered while receiving messages
                        </td>
                    </tr>
                    <tr>
                        <td>TimeoutsSending</td>
                        <td>long</td>
                        <td>
                            Number of timeouts encountered while sending messages
                        </td>
                    </tr>
                </table>
            </subsection>
        </section>
    </body>
</document>