NGINX.COM
Web Server Load Balancing with NGINX Plus


[Editor – The NGINX ModSecurity WAF module for NGINX Plus officially went End-of-Sale as of April 1, 2022 and is transitioning to End-of-Life effective March 31, 2024. For more details, see F5 NGINX ModSecurity WAF Is Transitioning to End-of-Life on our blog.]

We are excited to announce NGINX Plus Release 10 (R10), our most significant release yet. NGINX Plus extends NGINX Open Source with advanced functionality and award‑winning support, providing customers with a complete application delivery solution. With this release we are providing a number of new features to dramatically improve the security and performance of applications delivered by NGINX Plus, along with additional features for improved network integration and support for customization of NGINX Plus through scripting.

[Editor – For more details about key new features in NGINX Plus R10, see these related resources:

]

NGINX Plus R10 features the initial release of our web application firewall (WAF), powered by ModSecurity and fully supported by NGINX, Inc. Web application attacks increased by 50% in the past year and DDoS attacks more than doubled, according to Akamai. Every application is now at risk of being attacked. NGINX ModSecurity WAF helps protect web applications from malicious users and gives customers a versatile tool to help keep their apps and data safe.

Protect your applications using NGINX ModSecurity WAF, included in the NGINX Plus R10 release.
NGINX ModSecurity WAF blocks intruders

NGINX ModSecurity WAF is based on the new ModSecurity 3 software and runs natively within NGINX Plus. Available as an additional‑cost option in our dynamic modules repository and supported by NGINX, Inc., it has been tested thoroughly with NGINX Plus. We are working with Trustwave and will maintain tested updates as we add features, improve performance, and address any issues.

Two additional new features further enhance the security capabilities of NGINX Plus:

  • JSON Web Tokens – Many of our customers use NGINX Plus as an API gateway, and have asked us for a common and standard way of authenticating access to APIs at the NGINX Plus layer. To address that need, with this release we are adding support for authentication using JSON Web Tokens (JWTs).

    NGINX Plus can now validate a JWT before allowing clients access to APIs. This feature enables application administrators to secure access to their APIs with an open standard, avoiding vendor lock‑in to a proprietary standard. Native JWT support also reduces complexity for application administrators by offloading authentication operations – such as the validation of OAuth 2.0‑compliant OpenID Connect tokens – from application servers to NGINX Plus.

  • “Dual‑stack” support for ECC and RSA certificates – With NGINX Plus R10, you can publish SSL/TLS services using both RSA and ECC certificates. NGINX Plus selects the optimal certificate based on each client’s capabilities, allowing modern clients to use higher‑speed ECC certificates while still supporting legacy RSA‑only clients. ECC certificates can be up to 3x quicker than equivalent‑strength RSA certificates; this translates to more SSL/TLS connections per server and faster SSL/TLS handshakes.

In addition to security features, NGINX Plus R10 includes:

  • Transparent proxy support – Although many modern HTTP applications can be configured to rely on an X-Forwarded-For header, some legacy applications and other TCP or UDP services refer to the source IP address of the transaction for logging, security, or authentication purposes.

    NGINX Plus can now ‘spoof’ the source IP address and port of HTTP and TCP connections and UDP datagrams that it forwards to upstream servers. This can be used to provide IP transparency, a configuration where NGINX Plus sends packets with the remote client’s IP address so that the upstream server sees the packets as originating from that address rather than a local IP address on the NGINX Plus server. This feature can also be used to enable Direct Server Return for UDP‑based protocols.

  • NGINX JavaScript module support – The NGINX JavaScript module is the next‑generation configuration and control language for NGINX and NGINX Plus, giving users deep and fine‑grained control over how their applications are delivered and secured. In this preview release, the NGINX JavaScript module increases your control over HTTP, TCP, and UDP traffic, generating responses and making precise decisions to route requests to the optimal servers.
  • Further improvements to TCP and UDP load balancing – Extensions to the Stream module add support for more NGINX variables, calculations using the map directive, support for A/B testing with the split_clients directive, Geo and GeoIP operations, and selective routing (variable parameter to the proxy_pass directive). These extensions enable you to create more sophisticated TCP and UDP load‑balancing policies, driven by the NGINX configuration language and the new NGINX JavaScript integration.

NGINX Plus R10 in Detail

NGINX ModSecurity Web Application Firewall

The headline feature in NGINX Plus R10 is the initial release of our WAF, built on the well‑known and trusted ModSecurity technology. Since its initial open source release in 2002, ModSecurity has been helping to protect some of the world’s largest web properties against malicious users. It’s commonly called the “Swiss Army® knife” of security. NGINX ModSecurity WAF is an additional‑cost option, and is provided to subscribers through our dynamic modules repository.

NGINX ModSecurity WAF is a must‑have solution to help secure critical applications. It provides a cost‑effective alternative to inflexible and costly hardware appliances, such as those provided by F5, Citrix, and Imperva, while also exceeding their capabilities with the flexibility of software. NGINX ModSecurity WAF can be deployed in any environment – on‑premises servers, and public, private, and hybrid clouds.

NGINX ModSecurity WAF protects your websites and applications from DDoS attacks
NGINX ModSecurity WAF helps protect against DDoS attacks

A WAF operates on a database of “rules” that define malicious behaviors to be blocked and/or logged. The OWASP ModSecurity core rule set (CRS) is one of the most widely used rule sets with ModSecurity. NGINX ModSecurity WAF uses the OWASP CRS to identify and block a broad range of application attacks, with features such as:

  • Layer 7 attack protection – Protect your applications from a broad range of attacks, such as HTTP violations, SQL injection, XSS, RFI, and LFI attacks, and more.
  • DDoS mitigation – Maintain continuous uptime by mitigating and lessening the effect of sophisticated application‑level DDoS attacks and botnets.
  • Real‑time denylists – Automatically block known malicious users by denying traffic from IP addresses that are known to be malicious based on reputation.
  • PCI-DSS 6.6 Compliance – Start complying with PCI-DSS 6.6 requirements for safe online transactions.
  • Audit logging – Respond more quickly to attacks and other anomalous application traffic using the information in detailed logs.

Additional rule sets are also available from different vendors, such as TrustWave, at varying cost levels. In addition, you can use the powerful ModSecurity rules language to define your own custom rules that augment whatever rule sets you are using.

Support for NGINX ModSecurity WAF is provided directly by NGINX, Inc. Our support team can help install, configure, and debug issues with the WAF and the OWASP core rule set.

NGINX ModSecurity WAF is available as a dynamic module in the NGINX Plus repository that you install using standard package management tools. These commands are for Debian‑based operating systems:

# apt-get update
# apt-get install nginx-plus
# apt-get install nginx-plus-module-modsecurity

Note that only subscribers who have purchased the NGINX ModSecurity WAF module, and subscribers and evaluators who have requested access, can download the nginx-plus-module-modsecurity package.

To load the NGINX ModSecurity WAF module, include the load_module directive in the top‑level “main” context of the NGINX Plus configuration file:

To enable NGINX ModSecurity WAF with NGINX Plus, include the modsecurity directive along with the modsecurity_rules_file directive to specify the rule set:

Then reload the NGINX Plus configuration:

# nginx -t && nginx -s reload

Native JWT Support for OAuth 2.0 and OpenID Connect

With native support for the JSON Web Token (JWT) authentication standard, NGINX Plus R10 makes it easy to add sophisticated authentication solutions to your applications and APIs.

JWT (pronounced “jot”) tokens, defined in RFC 7519, are the underlying data format for user information in the OpenID Connect standard, which is the standard identity layer on top of the OAuth 2.0 protocol. Deployers of APIs and microservices are also turning to the JWT standard for its simplicity and flexibility.

[Editor – For use cases that leverage the native JWT support, see these blogs:

]

To provide authentication services for APIs, NGINX Plus R10 validates JWTs
NGINX Plus validates the JWT before allowing clients access

As a reverse proxy and load balancer, NGINX Plus sits in front of applications, making it ideally positioned to simplify application development by offloading the validation of the JWT supplied in each HTTP request. This provides two benefits. First, NGINX Plus can help stop unauthenticated, malformed, and malicious requests from reaching the application, protecting it from the effort and risk involved in handling such requests.

The second benefit is that NGINX Plus has access to all of the fields in the validated JWT (after signature verification) and can use the inherent power and flexibility of its configuration syntax to provide sophisticated authentication solutions for both microservices and APIs:

  • A typical use case for microservices is to have NGINX Plus validate the JWT and provide the identity of the authenticated user to the backend application as an HTTP header. This eliminates the need to implement the same authentication functionality over and over, in every microservice.
  • For APIs, NGINX Plus can rate limit access on a true per‑user basis instead of relying on the approximate mapping of IP addresses to end users.

The following sample NGINX Plus configuration snippet shows how to use JWTs to protect a website.

The auth_jwt directive tells NGINX Plus to use JWT to authenticate users making requests for a domain, in this case myrealm. The auth_jwt_key_file directive indicates which JSON Web Key (JWK) to use to validate the token signature; it functions like the public key in SSL/TLS encryption. The file location must be accessible to NGINX Plus.

As NGINX Plus validates and parses the token, it automatically creates NGINX variables for the “claims” in the JWT, which represent entities associated with it (its issuer, the user to whom it was issued, and the intended recipient, for example). The variable names all begin with $jwt_claim_. You can then use the add_header directive to have NGINX Plus pass a claim to the backend servers in the form of an HTTP header set to the value of the $jwt_claim_ variable. In our example, NGINX Plus passes the user identity to the backend application in the $jwt_claim_sub variable, which corresponds to the user ID (sub claim) in the JWT.

In NGINX Plus R8 we released a technology preview of OAuth2 support. In the NGINX Plus R10 implementation we’ve taken in feedback from our customers to deliver a production‑ready implementation that reaches the most valuable use cases in the complex world of authenticating users and computers.

“Dual‑Stack” RSA and ECC Certificate Support

There are plenty of reasons now to start SSL/TLS encrypting all application traffic. Google rewards SSL/TLS‑encrypted sites with higher search engine rankings. In addition, modern web standards, such as HTTP/2, are mandating SSL/TLS encryption for all websites.

With NGINX Plus R10, you can publish SSL/TLS services using both RSA and ECC certificates. In our testing, ECC certificates were up to 3x quicker than equivalent‑strength RSA certificates; this translates to more SSL/TLS connections per server and faster SSL/TLS handshakes. NGINX Plus selects the optimal certificate based on each client’s capabilities, allowing modern clients to use higher‑speed ECC certificates while still supporting legacy RSA‑only clients.

To support both RSA and ECC certificates, in the configuration for a virtual server simply include a pair of ssl_certificate and ssl_certificate_key directives for each certificate type, as shown in the following example.

Transparent Proxy

We are continuously adding features to NGINX Plus, such as TCP and UDP load balancing, to support a broader range of applications and deployment models. With NGINX Plus R10 we have added a transparent‑proxy capability that allows NGINX Plus to send packets to upstream servers using any source IP address and port. This enables configurations such as IP Transparency and Direct Server Return.

IP Transparency is a configuration where the load balancer (NGINX Plus) uses the remote client’s IP address as the source IP address in packets it sends to upstream servers. This means that upstream servers see packets as originating from the remote client’s IP address, rather than from a local IP address on the load balancer. This is significant when applications refer to the source IP address for logging, security, rate‑limiting, or authentication purposes.

IP Transparency is also a building block for a network load‑balancing technique called Direct Server Return (DSR). NGINX Plus can perform DSR for UDP‑based protocols (but not TCP or HTTP), allowing the return packets to completely bypass the load balancer and go directly to the remote client.

NGINX Plus supports Direct Server Return in its release r10, where servers reply directly to clients
In DSR mode, the backend server responds directly to the client

IP Transparency and DSR are configured with the new transparent parameter to the proxy_bind, fastcgi_bind, memcached_bind, scgi_bind, and uwsgi_bind directives. The following example shows how to set up DSR for a DNS backend. The proxy_responses directive specifies that NGINX Plus does not need to see any server responses (zero is the appropriate value for DSR).

Note that passive health checks are not effective when DSR is enabled, because they involve NGINX Plus verifying that the server sent a response to the client. Configuring active application‑aware health checks is mandatory for a DSR configuration. For an example, please see our detailed instructions for configuring them for load-balanced DNS servers.

IP Transparency and DSR configurations are complex, with additional routing and packet‑rewriting requirements that fall outside the scope of the NGINX Plus software. For complete instructions, see IP Transparency and Direct Server Return with NGINX and NGINX Plus as Transparent Proxy on our blog.

The NGINX JavaScript Module for HTTP‑, TCP‑, and UDP‑Based Applications

[Editor – The NGINX JavaScript module was formerly called nginScript. The module became generally available in NGINX Plus R12 (and NGINX 1.11.10).

For detailed explorations of other NGINX JavaScript module use cases, see Use Cases for the NGINX JavaScript Module.

The code in this section is updated to use the js_import directive, which replaces the js_include directive in NGINX Plus R23 and later. For more information, see the reference documentation for the NGINX JavaScript module – the Example Configuration section shows the correct syntax for NGINX configuration and JavaScript files.]

NGINX Plus R10 includes a preview release of our new NGINX JavaScript configuration language. It’s not yet feature complete, and we welcome any feedback on the work so far. NGINX JavaScript enables you to use JavaScript code to perform complex and custom actions on HTTP, TCP, and UDP traffic. It provides a powerful new way for controlling how your applications are delivered and secured. With NGINX JavaScript you can:

  • Write “serverless” functions directly in NGINX Plus using the powerful JavaScript programming language
  • Format, manipulate, and transform API data
  • Provide simple TCP services, such as a time server
  • Use JavaScript to set NGINX variables, create custom load‑balancing decisions, cache keys, and more

The NGINX JavaScript preview is available in our dynamic modules repository. You can install it using standard package management tools. These commands are for Debian‑based operating systems:

# apt-get update
# apt-get install nginx-plus
# apt-get install nginx-plus-module-njs

To load the NGINX JavaScript modules for HTTP and TCP/UDP, include the load_module directive in the top‑level “main” context of the NGINX Plus configuration file:

Then reload the NGINX Plus configuration to load the NGINX JavaScript modules:

# nginx -t && nginx -s reload

NGINX Open Source users can obtain NGINX JavaScript from our open source code repository.

JavaScript code is not included directly in the NGINX Plus configuration. Instead, it is read in with the js_import directive. In this example, the JavaScript code for a simple “serverless” function is read in from /etc/nginx/conf.d/functions.js. The js_content directive instructs NGINX Plus to call the JavaScript function and return the results to the client.

The JavaScript code in /etc/nginx/conf.d/functions.js pads a character string with a specified set of characters:

Additional Features

NGINX Plus R10 introduces a number of additional improvements to aid you in flawless application delivery, including:

  • TCP/UDP load balancing, implemented in the Stream module, now has greater feature parity with HTTP load balancing. Newly supported modules include Split Clients for A/B testing, GeoIP to take actions based on the geographical location of clients, and Geo to define variables based on IP address. More information is available through additional NGINX variables, and you can perform routing decisions using a variable as the parameter to the proxy_pass directive.
  • A common problem for high‑traffic applications is ephemeral port exhaustion, where new connections to upstream servers can’t be created because the OS has run out of available port numbers. To overcome this, NGINX Plus now uses the IP_BIND_ADDRESS_NO_PORT socket option when available. This option allows source ports to be reused for outgoing connections to upstream servers, provided the standard “4‑tuple” (source IP address, destination IP address, source port, destination port) is unique. It is available on systems with Linux kernel version 4.2 and later, and glibc 2.22 and later.
  • NGINX Plus generates the new variable $request_id automatically for each new HTTP request, effectively assigning the request a unique “transaction ID”. This facilitates application tracing and brings APM capabilities to log‑analysis tools. The transaction ID is proxied to backend applications and microservices so that all parts of the system can log a consistent identifier for each transaction.
  • The proxy_request_buffering, fastcgi_request_buffering, scgi_request_buffering, and uwsgi_request_buffering directives now work with HTTP/2 and can be used to toggle request buffering.
  • The new http2_body_preread_size directive allows HTTP/2 clients to start sending the request body immediately. The directive controls the size of the buffer used before NGINX Plus starts reading the client request body.

NGINX Plus Extras Package Is Deprecated

As we preannounced at the release of NGINX Plus R9, R10 is the last release that will include the NGINX Plus Extras package.

We strongly recommend that you modify your installation and configuration procedures now to use the nginx-plus package and dynamically load the modules in the nginx-plus-extras package that you actually use. Starting in NGINX Plus R11, this will be the only possible way to use modules that are not built into the nginx-plus package.

To switch to the nginx-plus package and dynamic modules, perform these steps:

  1. Remove the nginx-plus-extras package and install nginx-plus and the dynamic modules you want to use. For Debian‑based systems, the appropriate set of commands is:

    # apt-get update
    # apt-get remove nginx-plus-extras
    # apt-get install nginx-plus
    # apt-get install module-name
  2. In the main (top‑level) context in /etc/nginx/nginx.conf, add a load_module directive for each dynamically loaded module:

  3. Check the new configuration for syntactic validity and reload it:

    # nginx -t && nginx -s reload

Upgrade or Try NGINX Plus

If you’re running NGINX Plus, we strongly encourage you to upgrade to Release 10 as soon as possible. You’ll pick up a number of fixes and improvements, and it will help us to help you if you need to raise a support ticket. Installation and upgrade instructions can be found at the NGINX Plus customer portal.

NOTE: NGINX Plus R10 is the last release that will include the nginx-plus-extras package. See NGINX Plus Extras Package Is Deprecated, above.

If you’ve not tried NGINX Plus, we encourage you to try it out for web acceleration, load balancing, and application delivery, or as a fully supported web server with enhanced monitoring and management APIs. You can get started for free today with a 30‑day evaluation and see for yourself how NGINX Plus can help you deliver and scale out your applications.

More Information about NGINX Plus R10

For more details about key new features in NGINX Plus R10, see these related resources:

[NGINX ModSecurity WAF officially went End-of-Sale as of April 1, 2022 and is transitioning to End-of-Life effective March 31, 2024. For more details, see F5 NGINX ModSecurity WAF Is Transitioning to End-of-Life on our blog.]

Hero image
Free O'Reilly eBook: The Complete NGINX Cookbook

Updated for 2024 – Your guide to everything NGINX



About The Author

Owen Garrett

Sr. Director, Product Management

Owen is a senior member of the NGINX Product Management team, covering open source and commercial NGINX products. He holds a particular responsibility for microservices and Kubernetes‑centric solutions. He’s constantly amazed by the ingenuity of NGINX users and still learns of new ways to use NGINX with every discussion.

About F5 NGINX

F5, Inc. is the company behind NGINX, the popular open source project. We offer a suite of technologies for developing and delivering modern applications. Together with F5, our combined solution bridges the gap between NetOps and DevOps, with multi-cloud application services that span from code to customer.

Learn more at nginx.com or join the conversation by following @nginx on Twitter.