Author: hiranya
Date: Thu Aug 15 23:06:07 2013
New Revision: 1514532
URL: http://svn.apache.org/r1514532
Log:
Documentation update
Added:
synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/nhttp.xml
Modified:
synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/pass_through.xml
Added:
synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/nhttp.xml
URL:
http://svn.apache.org/viewvc/synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/nhttp.xml?rev=1514532&view=auto
==============================================================================
---
synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/nhttp.xml
(added)
+++
synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/nhttp.xml
Thu Aug 15 23:06:07 2013
@@ -0,0 +1,734 @@
+<?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 - Non-blocking HTTP Transport</title>
+ </properties>
+ <body>
+ <section name="Non-blocking 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>
+ </ul>
+ </section>
+ <section name="Introduction" id="Introduction">
+ <p>
+ The non-blocking HTTP transport (NHTTP transport) was the
default HTTP transport of
+ Synapse 2.1 and all the releases that preceded it. Synapse 2.1
was the
+ last release of Synapse to use the NHTTP transport by default
to send and
+ receive HTTP traffic. In the following releases the NHTTP
transport has been replaced
+ by the new <a href="pass_through.html">Pass Through HTTP
transport</a>. The NHTTP
+ transport is still shipped with Synapse, and the interested
users may use it by
+ enabling it in the
<strong>SYNAPSE_HOME/repository/conf/axis2.xml</strong> file. The
+ sample Axis2 server distributed with Synapse, still uses the
NHTTP transport by
+ default.
+ </p>
+ <p>
+ The NHTTP transport is very stable, mature, and is capable of
handling
+ large volumes of HTTP traffic. However, the new Pass Through
transport is even
+ more efficient, faster and highly optimized to handle content
agnostic mediation.
+ Also, the new transport supports almost all the features and
options supported by
+ the NHTTP transport. The features that are not yet supported,
will be added to the
+ Pass Through transport in the near future. Therefore, it is
highly recommended to
+ use the Pass Through transport whenever possible, and enable
the NHTTP transport only
+ if you really need to use a feature that's still not supported
by the Pass Through
+ transport.
+ </p>
+ <p>
+ The NHTTP transport is 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 transport uses two separate I/O 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 NHTTP transport
+ uses separate configurable thread pools for processing
received messages through
+ the mediation engine. Settings related to configuring I/O
reactor threads and NHTTP
+ 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>
+ The Non-blocking HTTP transport is no longer configured by
default in the
+ <strong>SYNAPSE_HOME/repository/conf/axis2.xml</strong> file
of Synapse. If you
+ wish to use this transport, you must add the necessary
configurations to the axis2.xml
+ file. In general, you may enable the following components of
the NHTTP transport via
+ the axis2.xml file.
+ </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 should be 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>
+ To enable the HTTP transport listener, you must add the
following XML configuration
+ to the axis2.xml file.
+ </p>
+ <div class="xmlConf"><transportReceiver name="http"
class="org.apache.synapse.transport.nhttp.HttpCoreNIOListener">
+ <parameter name="port">8280</parameter>
+</transportReceiver></div>
+ <p>
+ The only required parameter is the port parameter. A
complete list 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"><parameter
name="port">8280</parameter></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"><parameter
name="bind-address">10.0.0.5</parameter></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"><parameter
name="hostname">10.0.0.5</parameter></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"><parameter
name="WSDLEPRPrefix">http://proxy.example.com:8080/</parameter></div>
+ </td>
+ <td>No</td>
+ <td>http://<host>:<port>/</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.nhttp.HttpGetRequestProcessor interface. If it
+ is required to customize the way Synapse handles
HTTP GET requests, one could
+ implement the above interface, and register the
custom class with Synapse using
+ this parameter. By default Synapse ships with an
HTTP GET request handler that
+ responds to ?wsdl and ?xsd requests and mediates
all the others.
+ <div class="xmlConf"><parameter
name="httpGetProcessor">foo.bar.CustomGETProcessor</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ <tr>
+ <td>disableRestServiceDispatching</td>
+ <td>
+ Determines whether Synapse should attempt to
dispatch REST calls to any
+ of the deployed proxy services. If set to true,
Synapse will not dispatch
+ REST calls to proxy services.
+ <div class="xmlConf"><parameter
name="disableRestServiceDispatching">true</parameter></div>
+ </td>
+ <td>No</td>
+ <td>false</td>
+ </tr>
+ <tr>
+ <td>priorityConfigFile</td>
+ <td>
+ Path to a traffic flow priority configuration
file. See the documentation
+ related to Synapse priority executors to learn
more about this feature.
+ <div class="xmlConf"><parameter
name="priorityConfigFile">repository/conf/priority.xml</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ <tr>
+ <td>endpointsConfiguration</td>
+ <td>
+ Path to an Axis2 URL endpoint configuration file.
This is a mechanism to
+ specify message builders at the inbound endpoint
level.
+ <div class="xmlConf"><parameter
name="endpointsConfiguration">repository/conf/endpoints.xml</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ </table>
+ <p>
+ All the above parameters are also applicable to the HTTPS
transport listener.
+ </p>
+ <p><a href="#Contents">[Back to top]</a></p>
+ </subsection>
+ <subsection name="HTTP Transport Sender" id="HTTPSender">
+ <p>
+ To enable the HTTP sender, add the following configuration
to the axis2.xml
+ file.
+ </p>
+ <div class="xmlConf"><transportSender name="http"
class="org.apache.synapse.transport.nhttp.HttpCoreNIOSender">
+ <parameter name="warnOnHTTP500" locked="false">*</parameter>
+</transportSender></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"><parameter
name="http.proxyHost">proxy.example.com</parameter></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"><parameter
name="http.proxyPort">8080</parameter></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"><parameter
name="http.nonProxyHosts">10.0.0.8|foo.com|*.bar.org</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ <tr>
+ <td>warnOnHTTP500</td>
+ <td>
+ A pipe ('|') separated list of content-types for
which Synapse will
+ log a warning when receiving an HTTP 500 response.
By default Synapse
+ outputs a warning for any HTTP 500 response,
irrespective of the content-type.
+ To configure Synapse to log warnings for HTTP 500
responses with no
+ content-type header, use the value 'none'.
+ <div class="xmlConf"><parameter
name="warnOnHTTP500">x-application/hessian|none</parameter></div>
+ </td>
+ <td>No</td>
+ <td>all content types</td>
+ </tr>
+ </table>
+ <p><a href="#Contents">[Back to top]</a></p>
+ </subsection>
+ <subsection name="HTTPS Transport Listener" id="HTTPSListener">
+ <p>
+ HTTPS listener supports all the parameters supported by the
+ HTTP listener. In addition, HTTPS listener supports
several SSL/TLS specific
+ parameters. To enable the HTTPS listener, add the
following configuration to the
+ axis2.xml
+ </p>
+ <div class="xmlConf"><transportReceiver name="https"
class="org.apache.synapse.transport.passthru.PassThroughHttpSSLListener">
+ <parameter name="port" locked="false">8243</parameter>
+ <parameter name="keystore" locked="false">
+ <KeyStore>
+ <Location>lib/identity.jks</Location>
+ <Type>JKS</Type>
+ <Password>password</Password>
+ <KeyPassword>password</KeyPassword>
+ </KeyStore>
+ </parameter>
+ <parameter name="truststore" locked="false">
+ <TrustStore>
+ <Location>lib/trust.jks</Location>
+ <Type>JKS</Type>
+ <Password>password</Password>
+ </TrustStore>
+ </parameter>
+ </transportReceiver></div>
+ <p>
+ A complete list of parameters supported by the HTTPS
listener is given below.
+ Information regarding the parameters also supported by the
HTTP listener are
+ duplicated here for reader's convenience.
+ </p>
+ <table>
+ <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"><parameter
name="port">8243</parameter></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"><parameter name="keystore"
locked="false">
+ <KeyStore>
+ <Location>lib/identity.jks</Location>
+ <Type>JKS</Type>
+ <Password>password</Password>
+ <KeyPassword>password</KeyPassword>
+ </KeyStore>
+</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ <tr>
+ <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"><parameter
name="truststore" locked="false">
+ <TrustStore>
+ <Location>lib/trust.jks</Location>
+ <Type>JKS</Type>
+ <Password>password</Password>
+ </TrustStore>
+</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ <tr>
+ <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"><parameter
name="SSLVerifyClient">require</parameter></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"><parameter
name="bind-address">10.0.0.5</parameter></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"><parameter
name="hostname">10.0.0.5</parameter></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.nhttp.HttpGetRequestProcessor interface. If it
+ is required to customize the way Synapse handles
HTTP GET requests, one could
+ implement the above interface, and register the
custom class with Synapse using
+ this parameter. By default Synapse ships with an
HTTP GET request handler that
+ responds to ?wsdl and ?xsd requests and mediates
all the others.
+ <div class="xmlConf"><parameter
name="httpGetProcessor">foo.bar.CustomGETProcessor</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ <tr>
+ <td>WSDLEPRPrefix</td>
+ <td>
+ A URL prefix that should be added to all the HTTP
endpoints exposed
+ through this transport listener. This prefix will
appear in all WSDLs
+ advertised by the transport. This is particularly
useful when Synapse
+ is fronted by a proxy server or a load balancer
and it is required to mention
+ the proxy/load balancer endpoints in the WSDLs
generated by Synapse. This
+ parameter has higher priority than the hostname
parameter.
+ <div class="xmlConf"><parameter
name="WSDLEPRPrefix">https://proxy.example.com:8443/</parameter></div>
+ </td>
+ <td>No</td>
+ <td>https://<host>:<port>/</td>
+ </tr>
+ </table>
+ <p><a href="#Contents">[Back to top]</a></p>
+ </subsection>
+ <subsection name="HTTPS Transport Sender" id="HTTPSSender">
+ <p>
+ As of today, HTTPS sender does not support sending messages
+ through an external proxy. Therefore some of the
parameters supported by the
+ HTTP sender (http.proxyHost, http.proxyPort etc.) cannot
be used with the
+ HTTPS sender. However, there are several SSL/TLS related
parameters that need
+ to be configured when setting up the HTTPS sender. The
default HTTPS sender
+ configuration in the axis2.xml file is shown below.
+ </p>
+ <div class="xmlConf"><transportSender name="https"
class="org.apache.synapse.transport.passthru.PassThroughHttpSSLSender">
+ <parameter name="keystore" locked="false">
+ <KeyStore>
+ <Location>lib/identity.jks</Location>
+ <Type>JKS</Type>
+ <Password>password</Password>
+ <KeyPassword>password</KeyPassword>
+ </KeyStore>
+ </parameter>
+ <parameter name="truststore" locked="false">
+ <TrustStore>
+ <Location>lib/trust.jks</Location>
+ <Type>JKS</Type>
+ <Password>password</Password>
+ </TrustStore>
+ </parameter>
+</transportSender></div>
+ <p>
+ Following table lists all the parameters supported by the
Pass Through HTTPS
+ sender.
+ </p>
+ <table>
+ <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"><parameter name="keystore"
locked="false">
+ <KeyStore>
+ <Location>lib/identity.jks</Location>
+ <Type>JKS</Type>
+ <Password>password</Password>
+ <KeyPassword>password</KeyPassword>
+ </KeyStore>
+</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ <tr>
+ <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"><parameter
name="truststore" locked="false">
+ <TrustStore>
+ <Location>lib/trust.jks</Location>
+ <Type>JKS</Type>
+ <Password>password</Password>
+ </TrustStore>
+</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ <tr>
+ <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"><parameter
name="HostnameVerifier">Strict</parameter></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"><parameter
name="novalidatecert">true</parameter></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"><parameter
name="customSSLProfiles">
+ <profile>
+
<servers>server1.example.com:443,server2.example.com:443</servers>
+ <KeyStore>
+ <Location>lib/identity1.jks</Location>
+ <Type>JKS</Type>
+ <Password>password</Password>
+ <KeyPassword>password</KeyPassword>
+ </KeyStore>
+ <TrustStore>
+ <Location>lib/trust1.jks</Location>
+ <Type>JKS</Type>
+ <Password>password</Password>
+ </TrustStore>
+ </profile>
+ <profile>
+ <servers>server3.example.com:443</servers>
+ <KeyStore>
+ <Location>lib/identity2.jks</Location>
+ <Type>JKS</Type>
+ <Password>password</Password>
+ <KeyPassword>password</KeyPassword>
+ </KeyStore>
+ <TrustStore>
+ <Location>lib/trust2.jks</Location>
+ <Type>JKS</Type>
+ <Password>password</Password>
+ </TrustStore>
+ </profile>
+</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ <tr>
+ <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"><parameter
name="CertificateRevocationVerifier" locked="false">
+ <CacheSize>100</CacheSize>
+ <CacheDurationMins></CacheDurationMins>
+</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ </table>
+ <p><a href="#Contents">[Back to top]</a></p>
+ </subsection>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Modified:
synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/pass_through.xml
URL:
http://svn.apache.org/viewvc/synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/pass_through.xml?rev=1514532&r1=1514531&r2=1514532&view=diff
==============================================================================
---
synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/pass_through.xml
(original)
+++
synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/pass_through.xml
Thu Aug 15 23:06:07 2013
@@ -330,8 +330,8 @@
<tr>
<td>port</td>
<td>
- The port number on which the HTTP listener should
listen.
- <div class="xmlConf"><parameter
name="port">8280</parameter></div>
+ The port number on which the HTTPS listener should
listen.
+ <div class="xmlConf"><parameter
name="port">8243</parameter></div>
</td>
<td>Yes</td>
<td>N/A</td>
@@ -493,22 +493,22 @@
configuration in the axis2.xml file is shown below.
</p>
<div class="xmlConf"><transportSender name="https"
class="org.apache.synapse.transport.passthru.PassThroughHttpSSLSender">
- <parameter name="keystore" locked="false">
- <KeyStore>
- <Location>lib/identity.jks</Location>
- <Type>JKS</Type>
- <Password>password</Password>
- <KeyPassword>password</KeyPassword>
- </KeyStore>
- </parameter>
- <parameter name="truststore" locked="false">
- <TrustStore>
- <Location>lib/trust.jks</Location>
- <Type>JKS</Type>
- <Password>password</Password>
- </TrustStore>
- </parameter>
- </transportSender></div>
+ <parameter name="keystore" locked="false">
+ <KeyStore>
+ <Location>lib/identity.jks</Location>
+ <Type>JKS</Type>
+ <Password>password</Password>
+ <KeyPassword>password</KeyPassword>
+ </KeyStore>
+ </parameter>
+ <parameter name="truststore" locked="false">
+ <TrustStore>
+ <Location>lib/trust.jks</Location>
+ <Type>JKS</Type>
+ <Password>password</Password>
+ </TrustStore>
+ </parameter>
+</transportSender></div>
<p>
Following table lists all the parameters supported by the
Pass Through HTTPS
sender.
@@ -657,34 +657,34 @@
Synapse will use the default SSL configuration,
configured under keystore
and truststore parameters.
<div class="xmlConf"><parameter
name="customSSLProfiles">
-<profile>
-
<servers>server1.example.com:443,server2.example.com:443</servers>
- <KeyStore>
- <Location>lib/identity1.jks</Location>
- <Type>JKS</Type>
- <Password>password</Password>
- <KeyPassword>password</KeyPassword>
- </KeyStore>
- <TrustStore>
- <Location>lib/trust1.jks</Location>
- <Type>JKS</Type>
- <Password>password</Password>
- </TrustStore>
-</profile>
-<profile>
- <servers>server3.example.com:443</servers>
- <KeyStore>
- <Location>lib/identity2.jks</Location>
- <Type>JKS</Type>
- <Password>password</Password>
- <KeyPassword>password</KeyPassword>
- </KeyStore>
- <TrustStore>
- <Location>lib/trust2.jks</Location>
- <Type>JKS</Type>
- <Password>password</Password>
- </TrustStore>
-</profile>
+ <profile>
+
<servers>server1.example.com:443,server2.example.com:443</servers>
+ <KeyStore>
+ <Location>lib/identity1.jks</Location>
+ <Type>JKS</Type>
+ <Password>password</Password>
+ <KeyPassword>password</KeyPassword>
+ </KeyStore>
+ <TrustStore>
+ <Location>lib/trust1.jks</Location>
+ <Type>JKS</Type>
+ <Password>password</Password>
+ </TrustStore>
+ </profile>
+ <profile>
+ <servers>server3.example.com:443</servers>
+ <KeyStore>
+ <Location>lib/identity2.jks</Location>
+ <Type>JKS</Type>
+ <Password>password</Password>
+ <KeyPassword>password</KeyPassword>
+ </KeyStore>
+ <TrustStore>
+ <Location>lib/trust2.jks</Location>
+ <Type>JKS</Type>
+ <Password>password</Password>
+ </TrustStore>
+ </profile>
</parameter></div>
</td>
<td>No</td>
