NGINX Plus provides a flexible replacement for traditional application delivery controllers (ADCs). As a software load balancer with a small footprint, NGINX Plus can be deployed just about anywhere – on bare metal, on a virtual machine, or in a container, and on premises or in a public, private, or hybrid cloud. This guide explains how to migrate the Citrix NetScaler ADC configuration for several common load‑balancer features to the NGINX Plus software load balancer. It covers the most commonly used features to get you started quickly.

NGINX Plus and NetScaler both act as a full reverse proxy and load balancer, so that the client sees the load balancer as the application and the backend servers see the load balancer as the client. This allows for great control and manipulation of the traffic. This guide focuses on basic load balancing. For information on extending the configuration with Layer 7 logic and scripting, see the article on migrating Layer 7 logic on the NGINX blog. It covers features such as content switching and request routing, rewriting, and redirection.

About NGINX and NGINX Plus

NGINX is an open source web server, reverse proxy, and load balancer that has grown in popularity in recent years due to its scalability. NGINX was first created to solve the C10K problem (serving 10,000 simultaneous connections on a single web server). NGINX’s features and performance have made it the go‑to solution at high‑performance sites – it now powers the majority of the 100,000 busiest websites in the world.

NGINX Plus is the commercially supported version of the open source NGINX software. NGINX Plus is a complete software load balancer and application delivery platform, extending the power of NGINX with a host of enterprise‑ready capabilities that are instrumental to building web applications at scale:

Prerequisites

This guide assumes you are familiar with NetScaler concepts and CLI configuration commands.

Familiarity with basic NGINX and NGINX Plus concepts and directives is also helpful; links to documentation are provided, but the guide does not explain NGINX Plus functioning in depth.

Mapping NetScaler Networking Concepts to NGINX Plus

The networking configuration for NetScaler defines three types of IP addresses, which can be easily mapped to NGINX Plus:

  • NetScaler IP address (NSIP) – Management IP address of a specific NetScaler appliance. The NGINX Plus equivalent is the host IP address of the NGINX Plus instance.
  • Subnet IP address (SNIP) – The source (client) IP address seen by backend servers in the load balancing configuration. By default, the NGINX Plus equivalent is the host IP address of the NGINX Plus instance as well.

    Both NGINX Plus and NetScaler use their routing table to choose the best IP address to use. With NetScaler, you manage the routing table in the NetScaler CLI or GUI, but with NGINX Plus you need to edit the system‑level routing for your Linux or FreeBSD OS. You can also use the proxy_bind directive in the NGINX Plus configuration to specify the source address used for a specific application.

  • Virtual IP address (VIP) – Address advertised to clients for the service provided by the backend servers. The VIP functions in the same way for both NetScaler and NGINX Plus: it shifts from the primary device or instance to the secondary in the case of a failover.

Converting NetScaler Load Balancer Configuration to NGINX Plus

NetScaler uses a CLI for configuration. Even changes made in the GUI are translated internally to CLI commands, so we’ll represent NetScaler configuration in the CLI format.

NGINX Plus instead defines configuration with directives in a text file. The following sections explain how to convert NetScaler configuration to NGINX Plus for these entities and features:

Virtual Servers

NetScaler uses only the combination of IP address and port to select the virtual server for a request. If you want to consider information in the Host header as well, you use AppExpert policies or a Content Switch Virtual Server to inspect it.

In contrast, the NGINX Plus definition of a virtual server in a server block can include both IP address‑port combinations and values in the Host header. Include the server_name directive to specify the values to match in the Host header. The list of parameters to the server_name directive can include multiple hostnames, wildcards, and regular expressions. You can include multiple server_name directives and multiple listening IP address‑port combinations within one NGINX Plus server block.

The following sample virtual server configuration is for a hostname that ends in .example.com.

NetScaler

add lb vserver myvserver HTTP 10.0.0.99 80

NGINX Plus

server {
listen 10.0.0.99:80;
server_name .example.com;
...
}

SSL/TLS Termination

Handling SSL/TLS termination is a common use case for ADC load balancers. Both NetScaler and NGINX Plus use OpenSSL libraries to perform the encryption/decryption. NGINX Plus uses the system libraries, so the OpenSSL version is determined by the OS. NetScaler uses a modified version of OpenSSL included within its firmware.

To define the key and certificate, NGINX uses the ssl_certificate* directives. The following load‑balancer configuration examples offload SSL/TLS termination from the backend servers.

NetScaler

add ssl certKey test.crt -cert test.crt -key test.key
add lb vserver mysslvserver SSL 10.0.0.98 443
bind ssl vserver mysslvserver -certkeyName test.crt

NGINX Plus

server {
listen 10.0.0.98:443 ssl;

ssl_certificate test.crt;
ssl_certificate_key test.key;
...
}

Service Group Entities

It is straightforward to migrate the NetScaler entities that make up Services and Service Groups to NGINX Plus. NetScaler uses three major entity types:

  • Server – IP address or hostname of a specific backend server
  • Service – Association of a server entity with a listening port and monitor
  • Service Group – Association of a pool of server entities and listening ports with a monitor

NGINX Plus uses the upstream block to represent a pool of backend (upstream) application servers. In the most basic configuration, a server directive for each server specifies its IP address or hostname.

The following load‑balancer configuration examples define a server pool called myapp with three servers in it.

NetScaler

add serviceGroup myapp HTTP
bind serviceGroup myapp 10.0.0.100 80
bind serviceGroup myapp 10.0.0.101 80
bind serviceGroup myapp 10.0.0.102 80

NGINX Plus

upstream myapp {
server 10.0.0.100:80;
server 10.0.0.101:80;
server 10.0.0.102:80;
}

Session Persistence

Session persistence is critical for stateless applications and is helpful for continuous delivery use cases. NetScaler and NGINX Plus handle session persistence in a similar way.

If it’s compatible with the application, the Sticky Cookie method is a good choice with NGINX Plus, as it is simple to configure and handles failover well. It works just like the cookie insert method in NetScaler: the load balancer adds a session cookie to the first response from a backend server to a given client. The client then includes the cookie in subsequent requests and the load balancer uses it to route the request to the same server. This method doesn’t require the load balancer to maintain information about session state, because the session data is stored in the client‑side cookie.

A logical difference between the products is that NetScaler defines session persistence in the configuration for a virtual server, whereas NGINX Plus defines it in the context of the backend server group (upstream).

The following load‑balancer configuration examples set up cookie‑based session persistence.

NetScaler

add lb vserver mysslvserver SSL 10.0.0.91 443 -persistenceType COOKIEINSERT -timeout 60 -cookieName mysession

NGINX Plus

upstream myapp {
server 10.0.0.100:80;
server 10.0.0.101:80;
server 10.0.0.102:80;

sticky cookie mysession expires=1h;
}

Another session persistence method available in both products takes advantage of a cookie or other token created by the session participants, such as a JSESSIONID. NGINX Plus calls this the Sticky Learn method. The load balancer maintains a table in memory to map each cookie to a specific backend server.

The following load‑balancer configuration examples set up session persistence based on the JSESSIONID found in an existing cookie.

NetScaler

set lb vserver mysslvserver -persistencetype RULE -rule 'HTTP.REQ.COOKIE.VALUE("jsessionid")' -resRule 'HTTP.RES.SET_COOKIE.COOKIE("jsessionid")'

NGINX Plus

upstream myapp {
server 10.0.0.100:80;
server 10.0.0.101:80;
server 10.0.0.102:80;

sticky learn create=$upstream_cookie_jsessionid
lookup=$cookie_jsessionid
zone=client_sessions:1m;
}

The third NGINX Plus session persistence method, Sticky Route, is comparable to NetScaler’s Custom Server ID Persistence. In this method a particular backend server is specified in each request.

Health Checks

NetScaler uses the term monitor for what NGINX Plus calls a health check. You associate a monitor directly with a NetScaler service or service group, whereas an NGINX Plus health check is defined in a location block.

With the following load‑balancer configuration examples, the load balancer sends a request for / to backend servers; by default, NetScaler sends HEAD requests and NGINX Plus sends GET requests. NetScaler marks the server as healthy if it returns response code 200, while with this default configuration NGINX Plus accepts any 2xx or 3xx code.

NetScaler

add lb monitor httphealth HTTP -respCode 200 -httpRequest "HEAD /"
bind serviceGroup myapp -monitorName httphealth

NGINX Plus

location / {
proxy_pass http://myapp;
health_check;
}

It’s also possible with both products to define additional characteristics of the request or response. The following examples mark a backend server as healthy if it returns response code 200 and the message body includes the text Welcometonginx!.

NetScaler

add lb monitor httphealth-ecv HTTP-ECV -send "GET /" -recv "Welcome to nginx!"
bind serviceGroup myapp -monitorName httphealth-ecv

NGINX Plus

match server_ok {
status 200;
body ~ "Welcome to nginx!";
}

server {
...

location / {
proxy_pass http://myapp;
health_check match=server_ok;
}
}

Summary of Converted Load Balancer Configuration

The following examples bring together the commands and directives from the preceding sections. The NGINX Plus configuration includes some additional directives not discussed above:

  • zone – Defines a shared memory zone used for health checks
  • proxy_set_header – Ensures that requests forwarded to the backend servers include the Host header, set to the value extracted from that header in the client request
  • proxy_http_version – Specifies HTTP version 1.1 for connections to the backend servers

NetScaler

add ssl certKey test.crt -cert test.crt -key test.key
add lb vserver myssl SSL 10.0.0.98 443 -persistenceType COOKIEINSERT -timeout 60 -cookieName mysession
bind ssl vserver myssl -certkeyName test.crt
add serviceGroup myapp HTTP
bind serviceGroup myapp 10.0.0.100 80
bind serviceGroup myapp 10.0.0.101 80
bind serviceGroup myapp 10.0.0.102 80
add lb monitor httphealth HTTP -respCode 200 -httpRequest "HEAD /"
bind serviceGroup myapp -monitorName httphealth
bind lb vserver mysslvserver myapp

NGINX Plus

upstream myapp {
zone myapp 64k;
server 10.0.0.100:80;
server 10.0.0.101:80;
server 10.0.0.102:80;

sticky cookie mysession expires=1h;
}

server {
listen 10.0.0.98:443 ssl default_server;

ssl_certificate test.crt;
ssl_certificate_key test.key;

proxy_set_header Host $host;

location / {
proxy_pass http://myapp;
health_check;
proxy_http_version 1.1;
}
}

Configuring High Availability

NGINX Plus and NetScaler handle high availability (HA) in similar but slightly different ways. NetScaler handles the monitoring and failover of the VIP in a proprietary way, whereas NGINX Plus uses a separate software package called nginx‑ha‑keepalived to handle the VIP and the failover process for a pair of NGINX Plus servers. The package implements the VRRP protocol to handle the VIP. Limited active‑active scenarios are also possible with the NGINX Plus keepalived package.

Logging in NetScaler and NGINX Plus

Logging and monitoring are important supporting functionality for load balancing. Both NGINX Plus and NetScaler support logging.

NetScaler logs errors in its event log and NGINX Plus in its error log. By default, NetScaler does not log individual requests, but can be configured to do so, using a separate weblog client. NGINX Plus has an access log for which you can define customized formats to log many metrics (as captured in variables) from both requests and responses.

The NGINX Plus Status module collects numerous statistics, which you can access via its API or display on the built‑in live activity monitoring dashboard. For details, see Logging and Monitoring in the NGINX Plus Admin Guide.

Revision History

  • Version 1 (November 2016) – Initial version (NGINX Plus R11, NGINX 1.11.5)