Configuring Transports¶
A transport protocol is responsible for carrying messages that are in a specific format. WSO2 Micro Integrator supports all the widely used transports including HTTP/S, JMS, VFS, as well as domain-specific transports like FIX. Each transport provides a receiver implementation for receiving messages, and a sender implementation for sending messages.
Configuring the HTTP/HTTPS transport¶
The HTTP and HTTPS PassThrough transports are enabled by default in the Micro Integrator.
See the following sections for a complete list of HTTP/HTTPS parameter.
Number of HTTP Listeners¶
The default HTTP transport (PassThrough transport) of WSO2 Micro Integrator has 4 HTTP/HTTPS listeners configured. This includes 2 PassThroughHttpListener
threads and 2 PassThroughHttpSSLListener
threads.
You can configure the number of listeners for the HTTP transport in the deployment.toml file:
[passthru_properties]
io_threads_per_reactor=2
You are able to define any number of listeners (by updating the io_threads_per_reactor
value) as there is no maximum limit defined in the code level.
Note
The number of listener threads is double the value of the io_threads_per_reactor
property because the same number of PassThroughHttpListener
and PassThroughHttpSSLListener
threads are created. For example, if you defined the value for the io_threads_per_reactor
property as 5, you have 5 PassThroughHttpListener
threads and 5 PassThroughHttpSSLListener
threads. Therefore, the total number of listeners are 10.
Connection Throttling¶
With the default HTTP transport (PassThrough transport) you can enable connection throttling to restrict the number of simultaneous open connections.
To enable connection throttling, update the following property in the deployment.toml
file:
[transport.http]
max_open_connections = 2
This will restrict simultaneous open incoming connections to 2. To disable throttling, delete the max_open_connections
setting or set it to -1.
Info
Connection throttling is never exact. For example, setting this property to 2 will result in roughly two simultaneous open connections at any given time.
Verifying certificate revocation¶
The default HTTPS transport listener (Secured PassThrough) and transport sender can verify with the certificate authority whether a certificate is still trusted before it completes an SSL connection. If the certificate authority has revoked the certificate, a connection will not be completed.
When this feature is enabled, the transport listener verifies client certificates when a client tries to make an HTTPS connection with the Micro Integrator. Therefore the client needs to send it's public certificate along with the requests to the Micro Integrator. The transport sender verifies server certificates when the Micro Integrator tries to make an HTTPS connection with a backend server.
When this feature is enabled, the Micro Integrator attempts to use the Online Certificate Status Protocol (OCSP) to verify with the certificate authority at the handshake phase of the SSL protocol. If the OCSP is not supported by the certificate authority, the Micro Integrator uses Certified Revocation Lists (CRL) instead. The verification process checks all the certificates in a certificate chain.
To enable this feature for the HTTP PassThrough, add the following parameters for the HTTP transport receiver and sender in the deployment.toml file:
[transport.http]
listener.certificate_revocation_verifier_enable = true
listener.certificate_revocation_cache_size = 1024
listener.certificate_revocation_cache_delay = 1000
listener.verify_client = "require"
[transport.http]
sender.certificate_revocation_verifier_enable = true
sender.certificate_revocation_cache_size = 1024
sender.certificate_revocation_cache_delay = 1000
Configuring Transport Level Security¶
Micro Integrator supports both SSL and TLS protocols. But since the SSL protocol is vulnerable to Poodle attacks, it is necessary to make sure that only TLS protocol versions are enabled.
Note
It is necessary to disable SSL in Carbon servers because of a bug (Poodle Attack) in the SSL protocol that could expose critical data encrypted between clients and servers. The Poodle Attack makes the system vulnerable by telling the client that the server does not support the more secure TLS (Transport Layer Security) protocol, and thereby forces it to connect via SSL. The effect of this bug can be mitigated by disabling the SSL protocol for your server.
To configure the enabled protocols, update the following property in the deployment.toml file:
[transport.http]
listener.secured_protocols = "TLSv1.2,TLSv1.3"
sender.secured_protocols = "TLSv1.2,TLSv1.3"
Disabling weak ciphers¶
A cipher is an algorithm for performing encryption or decryption. When you set the sslprotocol of your server to TLS, the TLS and the default ciphers get enabled without considering the strength of the ciphers. This is a security risk as weak ciphers, also known as EXPORT ciphers, can make your system vulnerable to attacks such as the Logjam attack on Diffie-Hellman key exchange. The Logjam attack is also called the Man-in-the-Middle attack. It downgrades your connection's encryption to a less-secured level (e.g., 512 bit) that can be decrypted with sufficient processing power.
To prevent these types of security attacks, it is encouraged to disable the weak ciphers. You can enable only the ciphers that you want the server to support in a comma-separated list in the ciphers attribute.
To configure the enabled ciphers, update the following property in the deployment.toml file:
[transport.https]
listener.parameter.PreferredCiphers = "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256"
Note
To check the above configuration changes related to SSL. Download testsslserver.jar and test with the following command.
$ java -jar testsslserver.jar localhost 8253
Configuring the VFS transport¶
This transport is used to process files in a specified source directory. After processing the files, the files are moved to a specified location or deleted. Note that files cannot remain in the source directory after processing because they will be processed again. Therefore, if you need to maintain these files or keep track of which files have been processed, specify the option to move them instead of deleting them after processing. If you want to move files into a database, use the VFS transport and the DBReport Mediator.
Note
When you transfer a file to a remote FTP location via VFS, the integrator tries to detect the FTP location by navigating from the root folder first. If the integrator does not have at least list permission to the root (/), the file transfer fails.
The VFS transport is enabled in the Micro Integrator server by default. Also, the VFS transport does not have any global parameters that can apply to all VFS use cases. Rather, it has a set of service-level parameters that must be specified when you create a proxy service or REST API artifact. The VFS transport supports the SFTP protocol with Secure Sockets Layer (SSL). The configuration is identical to other protocols with the only difference being the URL prefixes and parameters.
For more information, see service-level VFS parameters.
Configuring the TCP transport¶
To enable the TCP transport listener and sender, set the following parameters to true
in the deployment.toml file (stored in the MI_HOME/conf
directory).
Change the listener port as required.
[transport.tcp]
listener.enable = true
listener.port = 6060
sender.enable = true
Configuring the MSMQ transport¶
To enable the MSMQ transport listener and sender, set the following parameters to true
in the deployment.toml file (stored in the MI_HOME/conf
directory).
[transport.msmq]
listener.enable = false
sender.enable = false
Note the following:
- The MSMQ examples only work on Windows since they invoke the Microsoft C++ API for MSMQ via JNDI invocation.
- Download the
axis2-transport-msmq-2.0.0-wso2v2.jar
file and add it to theMI_HOME/dropins
directory. This file provides the JNI invocation required by MSMQ bridging. - Make sure that MQ is installed and running. For more information, see http://msdn.microsoft.com/en-us/library/aa967729.aspx.
- Make sure that you have installed Visual C++ 2008 (VC9) and that it works with Microsoft Visual Studio 2008 Express.
Configuring the FIX transport¶
This transport implementation is a module developed under the Apache Synapse project and it supports JMX. This transport is mainly used in conjunction with proxy services. FIX transport does not support any global parameters. All the FIX configuration parameters should be specified at service level. QuickFix 4J configuration parameters can be found here.
To enable the FIX transport listener and sender, set the following parameters to true
in the deployment.toml file (stored in the MI_HOME/conf
directory).
[transport.fix]
listener.enable = false
sender.enable = false
Download Quickfix/J. In the distribution archive you will find all the dependencies listed below. Add these JARs to the <MI_HOME>/libs
folder.
Note
See the Quickfix/J documentation on configuring FIX acceptors and initiators.
- mina-core.jar
- quickfixj-core.jar
- quickfixj-messages-fix40.jar
- quickfixj-messages-fix41.jar
- quickfixj-messages-fix42.jar
- quickfixj-messages-fix43.jar
- quickfixj-messages-fix44.jar
- slf4j-api.jar
- slf4j-log4j12.jar
Also download the following JAR and add it to the <MI_HOME>/libs
folder.
- log4j-1.2.17.jar
Warning
Note that WSO2 API Manager 3.0.0, 3.1.0, 3.2.0, and 4.0.0 are affected by the Log4j2 zero-day vulnerability, which has been reported to WSO2 on 10th December 2021. You can mitigate this vulnerability in your product by following our instructions and guidelines.
Configuring Sample FIX Applications¶
If you are using a binary distribution of Quickfix/J, the two samples (FIX messages sender/reveiver) and their configuration files are all packed to two JAR files called
quickfixj-examples-banzai-2.1.1.jar
and quickfixj-examples-executor-2.1.1.jar
. You will have to extract the
JAR file, modify the configuration files and pack them to a JAR file
again under the same name.
Change the banzai.cfg file in quickfixj-examples-banzai-2.1.1.jar (/quickfix/examples/banzai) by changing TargetCompID
to SYNAPSE
[default]
FileStorePath=target/data/banzai
ConnectionType=initiator
SenderCompID=BANZAI
TargetCompID=SYNAPSE
SocketConnectHost=localhost
StartTime=00:00:00
EndTime=00:00:00
HeartBtInt=30
ReconnectInterval=5
[session]
BeginString=FIX.4.0
SocketConnectPort=9876
[session]
BeginString=FIX.4.1
SocketConnectPort=9877
[session]
BeginString=FIX.4.2
SocketConnectPort=9878
[session]
BeginString=FIX.4.3
SocketConnectPort=9879
[session]
BeginString=FIX.4.4
SocketConnectPort=9880
[session]
BeginString=FIXT.1.1
DefaultApplVerID=FIX.5.0
SocketConnectPort=9881
Edit the executor.cfg file in quickfixj-examples-executor-2.1.1.jar (/quickfix/examples/executor) by changing TargetCompID
to SYNAPSE
and changing SocketAcceptPort
to 19876
.
[default]
FileStorePath=target/data/executor
ConnectionType=acceptor
StartTime=00:00:00
EndTime=00:00:00
HeartBtInt=30
ValidOrderTypes=1,2,F
SenderCompID=EXEC
TargetCompID=SYNAPSE
UseDataDictionary=Y
DefaultMarketPrice=12.30
[session]
BeginString=FIX.4.0
SocketAcceptPort=19876
[session]
BeginString=FIX.4.1
SocketAcceptPort=9877
[session]
BeginString=FIX.4.2
SocketAcceptPort=9878
[session]
BeginString=FIX.4.3
SocketAcceptPort=9879
[session]
BeginString=FIX.4.4
SocketAcceptPort=9880
[session]
BeginString=FIXT.1.1
DefaultApplVerID=FIX.5.0
SocketAcceptPort=9881
Configuring the MQTT transport¶
To enable the MQTT transport listener and sender, set the following parameters to true
in the deployment.toml
file (stored in the MI_HOME/conf
directory).
[transport.mqtt]
listener.enable = false
sender.enable = false
Configuring the WebSocket transport¶
To enable the WebSocket transport sender, set the following parameters to true
in the deployment.toml
file (stored in the MI_HOME/conf
directory).
[transport.ws]
sender.enable = false
To enable the secured WebSocket transport sender, set the following parameters to true
in the deployment.toml
file (stored in the MI_HOME/conf
directory.
[transport.wss]
sender.enable = false
Configuring the UDP transport¶
To enable the MSMQ transport listener and sender, set the following parameters to true
in the deployment.toml
file (stored in the MI_HOME/conf
directory).
[transport.udp]
listener.enable = false
sender.enable =false
Configuring custom transports¶
Other than the transports defined above, you can use a custom transport that enables you to add a new transport to the Micro Integrator. Custom transport configurations contain senders and listeners that you can define. A custom transport configuration is as follows.
[[custom_transport.listener]]
class="org.wso2.micro.integrator.TransportListener"
protocol = "protocol"
[[custom_transport.sender]]
class="org.wso2.micro.integrator.TransportSender"
protocol = "protocol"
parameter.'transport.param' = true
You can define the listener and sender classes in the class
parameter. Any additional parameter can be passed to the configuration using parameter
. The following section involves using a custom transport to configure HL7 transport.
Configuring the HL7 transport¶
The HL7 transport allows you to handle Health Level 7 International (HL7) messages.
Adding the transport¶
HL7 is not shipped by default in the pack. To make the transport available, download the HL7_ZIP, extract it, and copy both the .jar files inside it to the <MI_HOME>/dropins
folder.
Enabling the transport¶
Add the following configurations to the deployment.toml
file (stored in the <MI_HOME>/conf
folder):
[[custom_transport.listener]]
class="org.wso2.micro.integrator.business.messaging.hl7.transport.HL7TransportListener"
protocol = "hl7"
parameter.'transport.hl7.TimeOut' = 10000
[[custom_transport.sender]]
class="org.wso2.micro.integrator.business.messaging.hl7.transport.HL7TransportSender"
protocol = "hl7"
You can configure how long request threads wait for the application's response by specifying the parameter.'transport.hl7.TimeOut'
parameter as shown above. This configures the timeout in milliseconds at the transport level.
Change message encoding type¶
To control the encoding type of incoming HL7 messages, set the following JAVA system property: ca.uhn.hl7v2.llp.charset
.
Configuring the MailTo transport¶
When you use the Micro Integrator to mediate messages, the mediation sequence can be configured to send emails (over SMTP) or receive emails (Over POP3 or IMAP) by using the MailTo transport protocol.
The MailTo transport listener implementation can be configured by setting the parameters as described in the JavaMail API documentation. For IMAP related properties, see IMAP Package Summary. For POP3 properties, see POP3 Package Summary. The MailTo transport listener also supports the following transport parameters in addition to the parameters described in the JavaMail API documentation.
-
Configuring the MailTo listener
The MailTo transport listener is enabled by default. For more information, see About MailTo Transport.
See the complete list of MailTo parameters.
-
Configuring the MailTo sender
[[transport.mail.sender]] name = "mailto" parameter.hostname = "smtp.gmail.com" parameter.port = "587" parameter.enable_tls = true parameter.auth = true parameter.username = "demo_user" parameter.password = "mailpassword" parameter.from = "[email protected]"
Note
In addition to enabling the MailTO transport, the following parameters are used in the above configuration to set a default email account as the mail sender. You can override this default mail sender by specifying an email sender account within your mediation sequence.
parameter.from
: The email address from which mails will be sent.parameter.username
: The user name of the email account (mail sender). Note that in some email service providers, the user name is the same as the email address specified for the 'From' parameter.parameter.password
: The password of the email account (mail sender).
If you want to use multiple mail boxes to send emails, make a copy of the default MailTo sender configuration in the
MI_HOME/conf/deployment.toml
file and change the transport sender name. For example, addmailtoWSO2
as the name.For a list of parameters supported by the MailTo transport sender, see SMTP Package Summary. You can add these parameters into the mail transport as custom parameters by appending relevant parameters surrounded by single quotes into the parameter section. For example, to add
mail.smtp.localport
parameter into the mail transport, toml configuration would beparameter.'mail.smtp.localport'=5000
.In addition to the parameters described there, the MailTo transport sender supports the following custom parameters.
transport.mail.SMTPBccAddresses
: If one or more e-mail addresses need to be specified as BCC addresses for outgoing mails, this parameter can be used. You can enter a comma-separated list of e-mail addresses.transport.mail.Format
: Format of the outgoing mail. Possible values are Text and Multipart.
Configuring the JMS transport¶
The Java Message Service (JMS) transport in WSO2 Micro Integrator allows you to easily send and receive messages to queues and topics of any JMS service that implements the JMS specification.
Java Message Service (JMS) is a widely used API in Java-based Message Oriented Middleware(MOM) applications. It facilitates loosely coupled, reliable, and asynchronous communication between different components of a distributed application. It supports two asynchronous communication models for messaging as follows:
- Point-to-point model: In this model message communication happens from one JMS client to another JMS client through a dedicated queue.
- Publish and subscribe model: In this model message communication happens from one JMS client(publisher) to many JMS clients(subscribers) through a topic.
JMS supports two models for messaging as follows:
- Queues: point-to-point.
- Topics: publish and subscribe.
- Shared Topic Subscription
- JMSX Delivery Count
- JMS Message Delivery Delay
The JMS transport implementation comes from the WS-Commons Transports project, and it makes use of JNDI to connect to various JMS brokers. As a result, WSO2 Micro Integrator can work with any JMS broker that offers JNDI support.
To enable the JMS transport sender and listener in the Micro Integrator, you need to update the deployment.toml file (stored in the MI_HOME/conf
directory) with the connection parameters for your JMS broker you are using. Be sure to add the required libraries to the MI_HOME/lib
directory.
See the following topics for instructions on how to configure the Micro Integrator with different types of brokers:
- Connecting to ActiveMQ
- Connecting to Apache Artemis
- Connecting to HornetQ
- Connecting to IBM WebSphere App Server
- Connecting to IBM WebSphere MQ
- Connecting to JBossMQ
- Connecting to MSMQ
- Connecting to RabbitMQ
- Connecting to SwiftMQ
- Connecting to Tibco EMS
- Connecting to Oracle Weblogic
- Connecting to WSO2 MB
- Connecting to Multiple Brokers
Configuring the Multi-HTTPS transport¶
This transport is similar to the HTTPS PassThrough transport, but it allows you to have different SSL profiles with separate truststores and keystores for different hosts using the same WSO2 Micro Integrator. It can listen to different host IPs and ports for incoming HTTPS connections, and each IP/Port will have a separate SSL profile configured.
Top