Migrating Load Balancer Configuration from Citrix ADC to NGINX Plus

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

Note: Citrix ADC was formerly called Citrix NetScaler.

NGINX Plus and Citrix ADC 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’s the #1 web server at 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 Citrix ADC 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 Citrix ADC Networking Concepts to NGINX Plus

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

  • Citrix ADC IP address (NSIP) – Management IP address of a specific Citrix ADC 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 Citrix ADC use a routing table to choose the best IP address to use. With Citrix ADC, you manage the routing table in the Citrix ADC 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 Citrix ADC and NGINX Plus: if the primary device or instance fails, the VIP address is reassigned to the secondary.

Converting Citrix ADC Load Balancer Configuration to NGINX Plus

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

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

Virtual Servers

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

Citrix ADC 

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

Citrix ADC 

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 Citrix ADC entities that make up Services and Service Groups to NGINX Plus. Citrix ADC 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.

Citrix ADC 

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. Citrix ADC 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 Citrix ADC: 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 Citrix ADC 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.

Citrix ADC - Cookie-based 

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

NGINX Plus - Cookie-based 

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.

Citrix ADC - JSESSIONID-based 

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

NGINX Plus - JSESSIONID-based 

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 Citrix ADC’s custom server ID persistence. In this method a particular backend server is specified in each request.

Monitors (Health Checks)

Citrix ADC uses the term monitor for what NGINX Plus calls a health check. You associate a monitor directly with a Citrix ADC 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, Citrix ADC sends HEAD requests and NGINX Plus sends GET requests. Citrix ADC marks the server as healthy if it returns response code 200, while with this default configuration NGINX Plus accepts any 2xx or 3xx code.

Citrix ADC - Default health check 

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

NGINX Plus - Default health check 

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

Citrix ADC - Custom health check 

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

NGINX Plus - Custom health check 

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

Citrix ADC 

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 Citrix ADC handle high availability (HA) in similar but slightly different ways.

Citrix ADC 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 Citrix ADC and NGINX Plus

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

Citrix ADC logs errors in its event log and NGINX Plus in its error log. By default, Citrix ADC 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 3 (April 2019) – Product name changed to Citrix ADC
  • 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)
Last modified September 27, 2024