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 Pass Through HTTP transport. The NHTTP transport is still shipped with Synapse, and the interested users may use it by enabling it in the SYNAPSE_HOME/repository/conf/axis2.xml file. The sample Axis2 server distributed with Synapse, still uses the NHTTP transport by default.
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.
The NHTTP transport is based on the Apache HTTP Core NIO library. This library is based on the reactor pattern, and the transport uses two separate I/O reactor instances:
The Non-blocking HTTP transport is no longer configured by default in the SYNAPSE_HOME/repository/conf/axis2.xml 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.
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.
To enable the HTTP transport listener, you must add the following XML configuration to the axis2.xml file.
The only required parameter is the port parameter. A complete list of supported parameters is given below.
| Parameter Name | Description/Example | Required | Default |
|---|---|---|---|
| port |
The port number on which the HTTP listener should listen.
<parameter name="port">8280</parameter>
|
Yes | N/A |
| bind-address |
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.
<parameter name="bind-address">10.0.0.5</parameter>
|
No | All available network interfaces |
| hostname |
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.
<parameter name="hostname">10.0.0.5</parameter>
|
No | localhost |
| WSDLEPRPrefix |
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.
<parameter name="WSDLEPRPrefix">http://proxy.example.com:8080/</parameter>
|
No | http://<host>:<port>/ |
| httpGetProcessor |
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.
<parameter name="httpGetProcessor">foo.bar.CustomGETProcessor</parameter>
|
No | N/A |
| disableRestServiceDispatching |
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.
<parameter name="disableRestServiceDispatching">true</parameter>
|
No | false |
| priorityConfigFile |
Path to a traffic flow priority configuration file. See the documentation
related to Synapse priority executors to learn more about this feature.
<parameter name="priorityConfigFile">repository/conf/priority.xml</parameter>
|
No | N/A |
| endpointsConfiguration |
Path to an Axis2 URL endpoint configuration file. This is a mechanism to
specify message builders at the inbound endpoint level.
<parameter name="endpointsConfiguration">repository/conf/endpoints.xml</parameter>
|
No | N/A |
All the above parameters are also applicable to the HTTPS transport listener.
To enable the HTTP sender, add the following configuration to the axis2.xml file.
Following parameters can be specified to customize the behavior of the HTTP sender.
| Parameter Name | Description/Example | Required | Default |
|---|---|---|---|
| http.proxyHost |
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.
<parameter name="http.proxyHost">proxy.example.com</parameter>
|
No | N/A |
| http.proxyPort |
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.
<parameter name="http.proxyPort">8080</parameter>
|
No | 80 |
| http.nonProxyHosts |
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.
<parameter name="http.nonProxyHosts">10.0.0.8|foo.com|*.bar.org</parameter>
|
No | N/A |
| warnOnHTTP500 |
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'.
<parameter name="warnOnHTTP500">x-application/hessian|none</parameter>
|
No | all content types |
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
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.
| Parameter Name | Description/Example | Required | Default |
|---|---|---|---|
| port |
The port number on which the HTTPS listener should listen.
<parameter name="port">8243</parameter>
|
Yes | N/A |
| keystore |
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:
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. <parameter name="keystore" locked="false">
<KeyStore>
<Location>lib/identity.jks</Location>
<Type>JKS</Type>
<Password>password</Password>
<KeyPassword>password</KeyPassword>
</KeyStore>
</parameter>
|
No | N/A |
| truststore |
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:
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. <parameter name="truststore" locked="false">
<TrustStore>
<Location>lib/trust.jks</Location>
<Type>JKS</Type>
<Password>password</Password>
</TrustStore>
</parameter>
|
No | N/A |
| SSLVerifyClient |
Use this parameter to enable client certificate verification (client
authentication). This option provides functionality similar to the
SSLVerifyClient directive
of Apache HTTPD. Supported values are:
<parameter name="SSLVerifyClient">require</parameter>
|
No | None |
| bind-address |
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.
<parameter name="bind-address">10.0.0.5</parameter>
|
No | All available network interfaces |
| hostname |
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.
<parameter name="hostname">10.0.0.5</parameter>
|
No | localhost |
| httpGetProcessor |
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.
<parameter name="httpGetProcessor">foo.bar.CustomGETProcessor</parameter>
|
No | N/A |
| WSDLEPRPrefix |
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.
<parameter name="WSDLEPRPrefix">https://proxy.example.com:8443/</parameter>
|
No | https://<host>:<port>/ |
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.
Following table lists all the parameters supported by the Pass Through HTTPS sender.
| Parameter Name | Description/Example | Required | Default |
|---|---|---|---|
| keystore |
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:
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. <parameter name="keystore" locked="false">
<KeyStore>
<Location>lib/identity.jks</Location>
<Type>JKS</Type>
<Password>password</Password>
<KeyPassword>password</KeyPassword>
</KeyStore>
</parameter>
|
No | N/A |
| truststore |
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:
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. <parameter name="truststore" locked="false">
<TrustStore>
<Location>lib/trust.jks</Location>
<Type>JKS</Type>
<Password>password</Password>
</TrustStore>
</parameter>
|
No | N/A |
| HostnameVerifier |
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:
<parameter name="HostnameVerifier">Strict</parameter>
|
No | Default |
| novalidatecert |
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.
<parameter name="novalidatecert">true</parameter>
|
No | false |
| customSSLProfiles |
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:
<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>
|
No | N/A |
| CertificateRevocationVerifier |
Enable revocation status validation of server certificates using
OCSP and
CRL. 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.
<parameter name="CertificateRevocationVerifier" locked="false">
<CacheSize>100</CacheSize>
<CacheDurationMins></CacheDurationMins>
</parameter>
|
No | N/A |
In addition to the basic parameters described in the previous section, the NHTTP transport provides some advanced options to tweak its runtime behavior and performance. These options should be configured in the SYNAPSE_HOME/lib/nhttp.properties file.
Following properties control various facets of Apache HTTP Core, the framework underlying the NHTTP transport.
| Parameter Name | Description/Example | Required | Default |
|---|---|---|---|
| http.socket.timeout |
Sets the TCP socket timeout in milliseconds
(See SO_TIMEOUT).
This applies to sockets opened by both transport listener and sender.
http.socket.timeout=20000
|
No | 60000 |
| http.socket.timeout.listener |
Sets the timeout in milliseconds for all the TCP sockets opened by the
transport listener. This overrides the value of
http.socket.timeout for the transport
listener.
http.socket.timeout.listener=20000
|
No | Value of http.socket.timeout |
| http.socket.timeout.sender |
Sets the timeout in milliseconds for all the TCP sockets opened by the
transport sender. This overrides the value of
http.socket.timeout for the transport
sender.
http.socket.timeout.sender=20000
|
No | Value of http.socket.timeout |
| http.connection.timeout |
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).
http.connection.timeout=30000
|
No | 0 |
| http.nio.interest-ops-queueing |
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
SelectionKey
immediately. Allowed values are either 'true' or 'false'.
http.nio.interest-ops-queueing=false
|
No | false |
| http.tcp.nodelay |
Setting this property to 'true' disables
Nagle's algorithm
for the HTTP connections. That is, outgoing data will not be buffered
and aggregated together
(See TCP_NODELAY).
http.tcp.nodelay=true
|
No | true |
| http.socket.buffer-size |
Sets the size of the I/O session buffers (in bytes) used by the transport
for reading incoming data and writing outgoing data.
http.socket.buffer-size=4096
|
No | 8192 |
| http.socket.rcv-buffer-size |
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 SO_RCVBUF).
http.socket.rcv-buffer-size=4096
|
No | 8192 |
| http.socket.snd-buffer-size |
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 SO_SNDBUF).
http.socket.snd-buffer-size=4096
|
No | 8192 |
| http.socket.linger |
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 SO_LINGER).
http.socket.linger=5000
|
No | -1 |
| http.socket.reuseaddr |
Sets the SO_REUSEADDR
socket option for the sockets created by the HTTP transport. Accepted
values are either 'true' or 'false'.
http.socket.reuseaddr=true
|
No | false |
| http.nio.select-interval |
Sets the time interval in milliseconds at which the I/O reactor wakes up
to check for timed out sessions and session requests.
http.nio.select-interval=2500
|
No | 1000 |
| io_threads_per_reactor |
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.
io_threads_per_reactor=4
|
No | Number of CPU cores |
| http.malformed.input.action |
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 CodingErrorAction
for more details on each of these options.
http.malformed.input.action=ignore
|
No | report |
| http.unmappable.input.action |
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 CodingErrorAction
for more details on each of these options.
http.malformed.input.action=ignore
|
No | report |
Following settings determine the behavior of Synapse with respect to mediating HTTP traffic.
| Parameter Name | Description/Example | Required | Default |
|---|---|---|---|
| nhttp_buffer_size |
Sets the size of the I/O buffers (in bytes) used to receive incoming
message data and write outgoing message data.
io_buffer_size=10240
|
No | 8192 |
| http.user.agent.preserve |
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 string 'Synapse-HttpComponents-NIO'.
http.user.agent.value property.
http.user.agent.preserve=true
|
No | false |
| http.server.preserve |
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 string 'Synapse-HttpComponents-NIO'.
http.server.preserve=false
|
No | true |
| nhttp_disabled_methods |
A comma separated list of HTTP methods that should be disabled. That is,
HTTP methods in this list will not be handled by the transport listeners.
Any attempt to invoke a disabled HTTP method will trigger an exception.
nhttp_disabled_methods=PUT,DELETE
|
No | N/A |
| http.connection.disable.keepalive |
Determines whether the transport sender should use keep-alive for
outbound HTTP connections. If set to true, Synapse will send outgoing
requests with the 'Connection: close' header, indicating that connection
should not be kept alive after the HTTP interaction is complete.
http.connection.disable.keepalive=true
|
No | false |
| http.count.connections |
Determines whether Synapse should keep track of the HTTP connections
established with target hosts. This information can be later accessed
via JMX (ConnectionsView).
http.count.connections=true
|
No | false |
The NHTTP transport uses two separate thread pools for mediating HTTP requests and responses through the Synapse mediation engine. The size of these thread pools determine the capacity of Synapse to handle concurrent HTTP traffic. Use the following properties to fine tune these thread pools according to your expected workload.
HTTP Request Thread Pool
| Parameter Name | Description/Example | Required | Default |
|---|---|---|---|
| snd_t_core |
Set the core size of the thread pool used by the NHTTP
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.
snd_t_core=100
|
No | 20 |
| snd_t_max |
The thread pools used by the NHTTP transport grow in size, as
more and more jobs are submitted to them. 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 snd_t_core.
snd_t_core=500
|
No | 100 |
| snd_alive_sec |
Specifies the idle time period (in seconds) for the excess threads in
the NHTTP transport thread pool. When the number of threads in the
pool is greater than snd_t_core,
this is the maximum time that excess idle threads will wait for new tasks
before terminating.
snd_alive_sec=10
|
No | 5 |
| snd_qlen |
Determines the length of the queue used by the NHTTP 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.
snd_qlen=1000
|
No | -1 |
HTTP Response Thread Pool
| Parameter Name | Description/Example | Required | Default |
|---|---|---|---|
| lst_t_core |
Set the core size of the thread pool used by the NHTTP
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.
lst_t_core=100
|
No | 20 |
| lst_t_max |
The thread pools used by the NHTTP transport grow in size, as
more and more jobs are submitted to them. 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 lst_t_core.
lst_t_core=500
|
No | 100 |
| lst_alive_sec |
Specifies the idle time period (in seconds) for the excess threads in
the NHTTP transport thread pool. When the number of threads in the
pool is greater than lst_t_core,
this is the maximum time that excess idle threads will wait for new tasks
before terminating.
lst_alive_sec=10
|
No | 5 |
| lst_qlen |
Determines the length of the queue used by the NHTTP 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.
lst_qlen=1000
|
No | -1 |
The NHTTP and Pass Through transports share the same logging framework. Therefore both transports support the same exact logging features and configuration options. Please refer the Pass Through transport logging configuration to learn more about the available features and how to enable them.