Configuring a NGINX Reverse Proxy

Authors: NealMiddlemore
Build basis: None.

Nginx (pronounced engine-x) is a free, open source high performance http server and reverse proxy. Nginx is known for its high performance, stability, rich feature set, simple configuration, and low resource consumption.

Please note that there has been mixed success with Nginx and this document is only supposed to provide information that worked at one site. This page is supported via the jazz.net forum and not IBM Support as this is not a certified proxy server at this time.

About NGINX

Nginx is one of a handful of servers written to address the C10K problem. Unlike traditional servers, Nginx doesn't rely on threads to handle requests. Instead it uses a much more scalable event-driven (asynchronous) architecture. This architecture uses small, but more importantly, predictable amounts of memory under load.

Whilst IBM doesn’t explicitly support Nginx as a reverse proxy for use with Jazz based applications, this article explains how to make Nginx work as a reverse proxy in this situation.

Out of the box, NGINX seems to work for everything except DOORS Next Generation. In DNG you will typically be able to log in and create a new project but not be able to create any new artefacts.

Setting up NGINX

There are two basic parts to setting up NGINX to work with CLM, the first is to set up the reverse proxy entries and the second part is to make the server stop ignoring invalid headers.

Part 1 - Adding the reverse proxy entries:

The way nginx and its modules work is determined in the configuration file. By default, the configuration file is named nginx.conf and placed in the directory /usr/local/nginx/conf, /etc/nginx, or /usr/local/etc/nginx.

The first thing that is needed is to add the application contexts to the reverse proxy configuration. A specific entry is needed for each application context you need to access, for a standard CLM deployment of RTC/RQM/DNG you would need to add JTS, CCM, QM, RM and ADMIN application contexts where ADMIN is used to manage lifecycle projects and the JTS is used to manage the underpinning Jazz Team Server (i.e. adding users, allocating licenses etc.). There are various parameters that can be set on each entry, the important one is proxy_pass as this defines the target of the pass through. Here is an example for JTS and CCM:

location /jts { 
    proxy_pass  https://123.123.123.123:443/jts; 
    proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504;
    proxy_pass_header on; 
    proxy_pass_request_headers on; 
    proxy_set_header        Host            $host; 
    proxy_set_header        X-Real-IP       $remote_addr; 
    proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for; 
}
location /ccm { 
    proxy_pass  https://123.123.123.123:443/ccm; 
    proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504; 
    proxy_pass_header on; 
    proxy_pass_request_headers on; 
    proxy_set_header        Host            $host; 
    proxy_set_header        X-Real-IP       $remote_addr; 
    proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
 }

Part 2 - Configure the server to ignore invalid headers

The major problem with Nginx and the default configuration is that whilst RTC and RQM seem to work perfectly well, DNG/RRC does not work. Setup can still be done even on the RM application and you can even create a project and add users to it, however the problems start when you try to create an artefact, this just will not work. To make the /rm application work, we need to deploy a server directive to the http server part of the core configuration: ignore_invalid_headers off;

Nginx defaults this value to ON and this directive is singularly responsible for making /rm work correctly. A more complete segment of the nginx.conf file would look like this:

server { # simple reverse-proxy
    listen       443;
    invalid_headers_off;
    server_name  domain2.com www.domain2.com;
    access_log   logs/domain2.access.log  main;
    }
     # pass requests for dynamic content to CLM, et al
     location /jts { 
    proxy_pass  https://123.123.123.123:443/jts; 
    proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504; 
    proxy_pass_header on; 
    proxy_pass_request_headers on; 
    proxy_set_header        Host            $host; 
    proxy_set_header        X-Real-IP       $remote_addr;
     proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for; 
}

location /ccm { 
    proxy_pass  https://123.123.123.123:443/ccm; 
    proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504; 
    proxy_pass_header on; 
    proxy_pass_request_headers on; 
    proxy_set_header        Host            $host; 
    proxy_set_header        X-Real-IP       $remote_addr; 
    proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
 }

location /rm { 
    proxy_pass  https://123.123.123.123:443/rm; 
    proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504; 
    proxy_pass_header on; 
    proxy_pass_request_headers on; 
    proxy_set_header        Host            $host; 
    proxy_set_header        X-Real-IP       $remote_addr; 
    proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for; 
}
location /qm { 
    proxy_pass  https://123.123.123.123:443/qm; 
    proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504;
     proxy_pass_header on; 
    proxy_pass_request_headers on; 
    proxy_set_header        Host            $host; 
    proxy_set_header        X-Real-IP       $remote_addr; 
    proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for; 
}

Once this has been deployed to the server and the http server has been restarted, /rm will work. To restart the Nginx server and reload the configuration file, this command can be issued:

nginx -s reload

For more information on Nginx configuration please refer to the NGINX Documents website.

Related topics: Deployment web home, Deployment web home

External links:

• IBM *NGINX Documents website

Additional contributors: TWikiUser, TWikiUser