NGINX Documentation

Migrating Load Balancer Configuration from Citrix NetScaler to NGINX Plus

NGINX Plus provides a flexible replacement for traditional hardware‑based 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 public, private, and hybrid clouds. This guide explains how to migrate the Citrix NetScaler ADC configuration for several common load‑balancer features to the NGINX Plus application delivery platform. 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 fine‑grained 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 Open Source and NGINX Plus

NGINX Open Source is an open source web server, reverse proxy, and load balancer that has grown in popularity in recent years due to its scalability. NGINX Open Source was first created to solve the C10K problem (serving 10,000 simultaneous connections on a single web server). Its 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 NGINX Open Source. NGINX Plus is a complete software load balancer and application delivery platform, extending the power of NGINX Open Source 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 software 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 same as for the NSIP: the host IP address of the NGINX Plus instance.

    Both NGINX Plus and NetScaler use a 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: if the the primary device or instance fails, the VIP address is reassigned to the secondary.

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 in that block 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. For more information on using Host and the server_name directive instead of IP addresses, see Server names at nginx.org.

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;
    #...
}

Directive documentation: listen, server, server_name

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‑level libraries, so the OpenSSL version is determined by the OS. NetScaler uses a modified version of OpenSSL included within its firmware.

To define the SSL/TLS key and certificate, NGINX Plus uses the [ssl_certificate] and [ssl_certificate_key] 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;
    #...
}

Directive documentation: listen, server, ssl_certificate and ssl_certificate_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 application servers. In the most basic configuration, there is a server directive in the upstream block for each server in the pool, specifying 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;
}

Directive documentation: server, upstream

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 NGINX Plus’ Sticky Cookie method is compatible with the application, it’s a good choice, 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 block).

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;
}

Directive documentation: server, sticky cookie, upstream

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;
}

Directive documentation: server, sticky learn, upstream

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.

Monitors (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;
}

Directive documentation: health_check, location, proxy_pass

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 Welcome to nginx!.

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;
    }
}

Directive documentation: health_check, location, match, proxy_pass, server

For more information about NGINX Plus health checks, see the NGINX Plus Admin Guide.

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.

For on‑premises deployments, NGINX Plus uses a separate software package called nginx-ha-keepalived to handle the VIP and the failover process for an active‑passive 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-ha-keepalived package.

Solutions for high availability of NGINX Plus in cloud environments are also available, including these:

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 API module collects numerous statistics, which you can access via the API, display on the built‑in live activity monitoring dashboard, or pass to third‑party monitoring tools. For more detail on logging and monitoring see the NGINX Plus Admin Guide.

Revision History

  • Version 2 (April 2018) – Updated information about high availability and the NGINX Plus API (NGINX Plus R13, NGINX Open Source 1.13.4)
  • Version 1 (November 2016) – Initial version (NGINX Plus R11, NGINX 1.11.5)