Migrating Load Balancer Configuration from Citrix NetScaler to NGINX Plus

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.

add lb vserver myvserver HTTP 10.0.0.99 80

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‑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.

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

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 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.

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

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 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.

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

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

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

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

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.

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

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

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

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

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

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

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)