MultiXTpm Generic Multiplexer
Open Source/Free Software
MultiXTpm Generic Multiplexer is an application built on top MultiXTpm Application
Its purpose is to provide application level multiplexing of messages arriving
from multiple connections into one or more connections, using application data for
The main use of such multiplexer is when there is a server application, that for
various reasons, can handle a definite number of open connections, and on
the other hand the number of client applications and the connection type is not
For example, an ISO 8583 Authorization Server is written to support
a limited number of connections to ISO 8583 Acquirer Gateways, and these connections
must be permanently opened. For this architecture to work, the ISO 8583 Acquirer
Gateways must handle hundreds of input connections which must be tunneled / multiplexed
in a well known number of output connections to the ISO 8583 Authorization Server.
Another example is from the SMPP (Short Message Peer-to-Peer) world. Many existing
SMSC (Short Message Service Centre) servers are built to be connected to ESMEs (External
Short Message Entity) using permanently opened connections. This architecture is
fine when the number of ESMEs is small, but when the number of ESMEs grows and this
unknown in advance, as in the case of internet users sending SMSs, there comes a
need to use some external system that will handle all the input connections and
route all messages thru a smaller number of opened connections.
Multiplexer is built to help solving such issues and it includes the following features:
- Can handle theoretically unlimited number of input connections.
- Can maintain an open connection with clients or a one request connection.
- Support for input connections arriving thru different TCP ports.
- Multiplex all
requests into a single output connection or into multiple output connections.
- When configured to support multiple output connections, it load balances all requests between
- Can multiplex various types of applications where each application has a different set of rules for multiplexing.
- Support output queues to the servers
with configurable timeouts.
- Can be customized to support any application level
- Support clients that send headerless messages.
In order for MultiXTpm Generic Multiplexer to do its job, the client applications
and the servers must adhere to some basic rules:
- Communications between the peers
must be message based, and there must be a field at the beginning of the message,
specifying the total length of message. The total length can be inclusive or exclusive
of the length field itself.
- A message received from a client, may contain a header
field that the multiplexer may override when forwarding to the server. If configured
as so, the multiplexer may override the field but will not add any data to the message.
- Every message forwarded to the server, must have a header field where the multiplexer
stores some data and expects it to be returned in the response exactly as it sent
it, it does not have to be at the same position.
- If the message received from a client does not contain a header, the configuration must include information
of the size of the header that the multiplexer can add
to the message before the message data. This header must be sent and received back because this is how the multiplexer knows how to
route back responses to client applications.
MultiXTpm Generic Multiplexer runtime environment comprises of 3 processes
at the minimum:
MultiXTpm - Application Server, Router, load balancer.
- Multiplexer Client FE - Listener and communications handler,
receivng requests from client applications and forwards them to the Server FE.
- Multiplexer Server FE - Connection initiator and communications
handler. This is the actual multiplexer that tunnels all requests to a definite
number of connections.
Multiplexer Client FE
This process acts as a Listener/Transport handler. It is responsible for the actual
communication with all client applications. This process always
acts as Listener, it never initiates calls. When a new connection is established,
it creates a new session object, it waits for incoming messages and when a full message is received, it is forwarded to
MultiXTpm process (in the context of the session created earlier) with a special
indication of the a Message Code configured for the input connection. This Message
Cdoe is used by the Server FE when selecting the server to forward the message to.
MultiXTpm in turn forwards the request to the appropriate Multiplexer
Server FE process for the actual tunneling of the message to the remote
server. When a response
comes from the Multiplexer Server FE process, it is forwarded back
to the originator of the request. The connection is kept open, waiting for the next
request, or disconnect from the client or an idle timer expires in which case the
connection is aborted. This process is multithreaded and all communication activities
are in NOWAIT manner, so it does not block on any call, so it can theoretically
process unlimited number of connections simultaneously. This process can have more
then one instance where each instance can manage a different range of ports. All
instances can run on a single machine or can be divided between multiple machines.
Multiplexer Server FE
This process is responsible to all communications and the tunneling of messages
to the remote servers. When
it starts, it receives from
MultiXTpm a list of addresses and ports of remote servers and it tries to connect to each one of them in order to establish a permanent connection.
When such a connection is established, it marks the connection as Active. From that point
on, every message that it receives from Client Server FE, and that
message has a Message Code as configured for the connection, is tunneled to the
server through that
connection. To enable the association of a response to a request, this process
sets (or adds) some value in the header of the message and the server has to send
that value back in the response. So when a response is received, using that specific value, the
process finds the request, and using the information saved in the request, the response
is routed back to the client. It is possible to configure more than one connection
to a single server or service. This is done by configuring the same “ForwardingMsgCode”
to a set of connections. When this process finds that more than one connection is
configured this way, it will always forward new messages to the connection with
lowest queue size, this way it load balances all the messages between all the connections. This process forwards
the requests as soon as it receives them, it does not wait for responses before
forwarding the next requests. When a connection is disconnected for some reason,
it waits for a pre configured timeout interval and tries to reconnect for a maximum
of preconfigured number of retries.
This is the main process within this architecture. When it starts, it reads a preconfigured
XML file where all configuration data is stored in. Among other things, it starts
the first instances of the other processes. When the other processes are started,
it provides them with some configuration data. It provides Multiplexer Client
FE the information about the TCP/IP ports to listen on for incoming
requests. It also provides Multiplexer Server FE
the information about the TCP/IP addresses and ports to connect to remote servers for multiplexing
MultiXTpm's main responsibilities are:
- Monitor the other processes for unexpected termination. When it realizes that
one of the processes has terminated, it restarts it if it is configured to do so.
- When a new request arrives from Multiplexer Client FE, it
routes the request to one or more Multiplexer Server FE processes for
handling the request.
- Monitor the queues for the Multiplexer Server FE processes. Based on configuration
MultiXTpm maintains a queue for each process.
- Receiving a response from Multiplexer Server FE processes
and forward the responses back to Multiplexer Client FE.
Following is a description of the Data Flow in MultiXTpm Generic Multiplexer.
Each request passes thru few phases starting from connection establishment
and ending with the connection closing. Between these two phases the Client is said
to be "in a session".
Following is a brief description of the various phases.
- The client establishes a connection.
- The client sends a request.
- Multiplexer Client FE Receives the request and validates
- The message is forwarded in its entirety using the Message Code configured for
the input connection for
internal routing purposes. If the request is the first one in the session, it is
MultiXTpm, otherwise it is forwarded directly to the Multiplexer Server
process that was previously elected by MultiXTpm
on the first call.
MultiXTpm, upon receiving the new request, searches its local configuration
data for an entry matching the Message Code specified in the request, it does not
scan the message AT ALL. If it finds such an entry, it elects the appropriate
Multiplexer Server FE process and queues the message for a later forwarding
to that process.
- If the queue for that process is empty or its size is below a preconfigured maximum,
the message is forwarded immediately to the process.
- Upon receiving the request, Multiplexer Server FE searches an opened connection
that configured to support the given Message Code and has the lowest queue size
among all connections that support the given Message Code. When it finds such a
connection, it tunnels the message through that connection.
- When a response is received, it is forwarded back to original Multiplexer
Client FE who forwarded the request.
- When the response from
MultiXTpm or Multiplexer Server FE is received, Multiplexer
Client FE checks that the connection with the client is still
valid and if so, it forwards the response.
- The response is sent to the client. At that point the client may elect to close
the connection and as a result, Multiplexer Client FE will
delete the session object. If the connection is not closed, Multiplexer Client
FE will use the same session object for handling future requests.
Multiplexer configuration is done thru the xml file located in the runtime directory.
Its default name is "TpmConfig.xml".
A description of this file and how to configure
it can be found
In addition to the standard fields that need to be configured,
there are few parameters that are required in order to configure the Multiplexer Links specifically.
The following Link parameters control the multiplexing rules used by the Link (Connection):
When configured for Multiplexer Client FE Links, it controls the
Message Code to use when forwarding a message to Multiplexer
Server FE. When configured for the Multiplexer Server FE
Links, it is used to decide which Link to use when a message with the specified
Message Code arrives.
Each message to be multiplexed must begin with a binary field that specifies the
total length of a message. It is only after an entire message is received, that
the message is processed. This field specifies the size of this field.
Possible values are:
- 1 - one byte. This implies that the total message size cannot exceed 255 bytes.
- 2 - two bytes. This implies that the total message size cannot exceed 64K bytes.
- 4 - Four bytes. This implies that the total message size cannot exceed 4G bytes.
Any other value specified will cause the Multiplexer throw an exception.
This parameter specifies whether the message size specified in the size field, includes
the size field itself.
A value of 1 means that the message size includes the size field.
Since the size field is binary, this parameter specifies if it is stored in network
format (Big Endian).
A value of 1 specifies that the size field is stored in network format (Big
When Multiplexer Server FE tunnels a message, it needs to save
some information in the message. The server that receives that message must return
that information in the response. This is used to associate th response with the
request. The value in this parameter specifies where in the message Multiplexer
Server FE can save that information and where it should retrieve it from
when it receives the response.
This parameter tells Multiplexer Server FE how many bytes in the
message are reserved for its context to be saved.
This parameter has meaning in Multiplexer Server FE only if
SwapContextOnResponse is specified. In this, before sending a response
to the client, Multiplexer Server FE swaps the values in the Sender
and Receiver Contexts.
This value specifies where in the message, the Receiver Context is located.
This value specifies the size for the Receiver Context when SwapContextOnResponse
is specified. It must be identical to the SenderContextSize value.
Tells Multiplexer Server FE that the Sender Context and the Receiver
Context values should be swapped on response.
When a client application sends a message that includes a header with space for
Multiplexer Server FE to store its context, this value should be
set to 1. When there is no such space in the message, Multiplexer Server FE
create such a space in front of the message data and its size is specified by
HeaderSize. The server that receives the message must be prepared to
receive such a message. When a response is received, these extra header bytes are
removed before forwarding the response to the client application.
This parameter tells Multiplexer Server FE how many bytes to insert
in front of the message when the original message does not contain any header to
be used it in order to save its Sender Context.
MultiXTpm Application Server is free software; you can redistribute
it and/or modify it under the terms of the
GNU General Public License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
MultiXTpm Application Server is distributed in source code format
and it supports: Windows OS, Linux, Solaris and HP Nonstop Server OSS.
The source code is packed in ZIP file and can be downloaded from SourceForge.net.
To Access the Download Page
at SourceForge.net you may click Here
For more information, Bug Reports, Feature Requests, and Support Requests, please
SourceForge.net Project Forums
MultiXTpm group at Yahoo Groups.
you may send an email to: