Universal Messaging server behind NGINX

Universal Messaging server behind NGINX Product Versions: Universal Messaging & webMethods Integration Server from 10.5 fix 8 onwards



This section covers the NGINX configuration for serving UM http requests and its detailed description.

To begin with, let’s consider a very basic setup where we expose an NGINX server port which is configured on um server settings. Clients who want to connect will be making requests to the NGINX server instead of UM directly. NGINX server takes care of redirection to the UM server

Below are the configuration that one needs to consider while configuring UM behind load balancer.

	events {
	worker_connections  1024;
http {
	default_type application/octet-stream;  
    #Log Settings
	log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                  '$status $body_bytes_sent "$http_referer" '
                  '"$http_user_agent" "$http_x_forwarded_for"';

	#create logs directory in /etc/nginx path before configuring these otherwise you can use default directory #path /var/log/nginx to configure error and access logs
	access_log  logs/access.log;
	error_log  logs/error.log warn;

	# Server will close idle connection after this timeout.
    keepalive_timeout 300s;

	# number of requests client can make over single connection.
	keepalive_requests 1000000;

	# This is a must, since UM client is currently sending: User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; #Windows NT 5.0)  and default 'msie6' matches this and causes nginx to close UM client connections
	keepalive_disable none;

    upstream umbackend {
		server localhost:11000;

		# maximum number of keep alive connections to maintain to each upstream server
		keepalive 100;
		# Server will close idle connection after this timeout.
        keepalive_timeout 300s;

		# number of requests client can make over single connection.
		keepalive_requests 1000000;		
server {
    	listen       80;
		server_name loadbalancer;
		# Important - nginx must continuously send data to UM client rather than buffering it
		proxy_buffering off;

		location / {
			proxy_pass http://umbackend;
			#Important - configure proxy http 1.1 protocol version to enable connection      
            #keep-alive and rewrite Connection header
            proxy_http_version 1.1;
			proxy_set_header Connection "";		

Required UM Configurations Details

Directives Required Value Explanation
proxy_buffering Off Default Value: on : This must be disabled for serving UM requests as UM does not send a content length to initial HTTP connections [see specification] as it uses it for a long lived persistent connection from a UM server to a UM client. This option optimises for stateless http environments however UM uses a streaming protocol.
proxy_pass Example: http://umhost:port Proxied UM server’s URL, UM should either be configured with nhp/nhps protocol. Proxy_pass would take http or https protocol accordingly to redirect the requests.
access_log logs/access.log You must create a logs directory inside /etc/nginx folder before starting the nginx or you can you the default log directory which is locate at /var/log/nginx. Client information will be written in the access log and by default access log will be written to a directory **logs/access.log,**You can override it by adding access_log directive with path of your choice.
error_log logs/error.log writes information about encountered issues of different severity levels to the error log. By default, the error log is located at logs/error.log
keepalive 100 Keepalive settings are important whenever upstream server needs to handle a high number of connections with the clients. Keepalive number of Idle connections that the upstream server can have. This is allowed in the upstream directive for the proxied server.
keepalive_requests 100000 Number of requests that can be served through one keepalive connection to an upstream server.[keep this a high value]
keepalive_ timeout 300s This sets a timeout to an idle connection that remains open for specified amount of time . Default time is 75seconds.
proxy_http_version 1.1 By default, nginx will have http version 1.0 which need to be overridden with http 1.1 version.
proxy_set_header connection “” And this directive used to set the headers, by default nginx sets connection header to close, due to which upstream server’s connections will closed by the nginx server. Hence this need to be set with empty value.

Load the configuration and start the nginx server

If you want to test on your NGINX set-up for your UM server, use the above configuration. Update proxy_pass with your running UM server’s HTTP Interface and update this in your /etc/nginx/nginx.conf file and start the server.

In the above configuration serves static files over HTTP on port 80 from the directory / opt/softwareag/UniversalMessaging/doc/ [ opt/softwareag is installation directory, you can configure to serve your own static file as well.]

nginx -s reload

Use the reload method of NGINX to achieve a graceful reload of the configuration without stopping the server
All the requests from clients which contains um1 in its URL segment, are forwarded to the proxied server which is defined in umbackend upstream.i.e umserver which is running locally on port 11000

Sample-Program to validate

package com.pcbsys.nirvana.client.nginx;
import com.pcbsys.nirvana.client.nChannel;
import com.pcbsys.nirvana.client.nChannelAttributes;
import com.pcbsys.nirvana.client.nConsumeEvent;
import com.pcbsys.nirvana.client.nEventListener;
import com.pcbsys.nirvana.client.nSession;
import com.pcbsys.nirvana.client.nSessionAttributes;
import com.pcbsys.nirvana.client.nSessionFactory;

public class sample implements nEventListener{
static nChannel channel;
static nSession session;
static int MSG_COUNT = 1000;

public static void main(String[ ] args) { try { sample s = new sample(); channel = s.createChannel(args); session = s.createSession(args[0]); nChannel channel = session.findChannel(s.getChannelAttributes(args[1])); for (int i = 0; i < MSG_COUNT; i++) { channel.publish(new com.pcbsys.nirvana.client.nConsumeEvent("TAG", "message".getBytes())); } } catch (Exception e) { e.printStackTrace(); } } public nChannel createChannel(String[] arg) throws Exception { nSession session = createSession(arg[0]); nChannelAttributes attr = getChannelAttributes(arg[1]); nChannel channel = session.createChannel(attr); channel.addSubscriber(this); return channel; }

private nChannelAttributes getChannelAttributes(String arg) throws Exception {
nChannelAttributes channelAttributes = new nChannelAttributes();
return channelAttributes;

public nSession createSession(String arg) throws Exception {
nSessionAttributes attr = new nSessionAttributes(arg);
nSession session = nSessionFactory.create(attr);
return session;

public void go(nConsumeEvent event) {
try {
if (event != null) {
System.out.println("Received event from " + this.channel + "event id " + event.getEventID());
} catch (Exception e) {

Inputs for the above program is as follows :

  1. Nginx server URL

  2. Channel name for the channel that you want to create

NGINX URL should contain the protocol that UM supports.

For example, if the NGINX server is running on host port 80 then the connection URL would be nhp ://

The above program publishes 1000 events to a specified channel and consumes it from the same channel.

Things to consider if there are dedicated servers configured based on the URL pattern

For example:

server {
listen 80;
server_name loadbalancer;
proxy_buffering off;
location = / umserver1 {
proxy_pass http://um1;
proxy_http_version 1.1;
proxy_set_header Connection “”;
location = /umserver2 {
proxy_pass http://um2;
proxy_http_version 1.1;
proxy_set_header Connection “”;
location = /umserver3 {
proxy_pass http://um3;
proxy_http_version 1.1;
proxy_set_header Connection “”;

As you can see, if you have set the directive location with the some specific pattern one has to use URL as follows to connect to nginx
i.e nhp://nginxhost:nginxport/umserver1, nhp://nginxhost:nginxport/umserver2, nhp://nginxhost:nginxport/umserver3

But if you are using the client below the version below 10.5 you must have to use the URL with an extra slash in order to work. i.e
nhp://nginxhost:nginxport//umserver1, nhp://nginxhost:nginxport//umserver2, nhp://nginxhost:nginxport//umserver3

For more details such as configuring with a secured socket layer please visit/read the below document:
Configuring UM behind NGINX Server (2).docx (211.3 KB)

1 Like

Good info. Beware of terminology. “Redirect” in an HTTP context (nginx) has a very specific meaning. Based upon the description here, there is no redirect but routing.

1 Like