Announcing NGINX Plus R13
We’re pleased to announce that NGINX Plus Release 13 (R13) is now available as a free upgrade to all NGINX Plus subscribers. NGINX Plus is a combined web server, load balancer, and content cache built on top of the open source NGINX software. NGINX Plus R13 includes new features focused on dynamic deployments, enhanced debugging capabilities, and improved security and performance.
A new API enables users to more easily perform common configuration tasks, such as dynamically changing upstream configuration to support the release of new application versions. The same API can also be used to pull the 40-plus exclusive metrics available in NGINX Plus. NGINX Plus R13 also introduces a new key-value store that can be managed by the API. This new API enables NGINX Plus to integrate seamlessly with external systems that drive upstream configurations and key-value stores.
NGINX Plus R13 also supports:
- Request mirroring – Duplicate all traffic received to a dedicated server. This server can then be used to monitor, inspect, and log application traffic without affecting the performance of production servers.
- nginScript enhancements – Extend NGINX further with programmatic configuration using nginScript, our custom NGINX implementation of JavaScript. The new interactive shell provides a console that shows all of the built-in objects for JavaScript. These objects can be investigated further to expose the available methods and primitives for each object.
- Build tool for dynamic modules – Create installable packages for the many third-party modules available for NGINX Plus with our new build tool.
Further enhancements include improvements to the cookie learn method for session persistence, HTTP trailers support, and a new dynamic module: HTTP substitutions filter.
Changes in Behavior
sticky_cookie_insert directive has been removed in NGINX Plus R13, having been deprecated with NGINX Plus R2.SecRequestBodyInMemoryLimit directive for ModSecurity is no longer supported. Customers may safely remove this directive, because the ModSecurity module will obey the request body handling defined by the NGINX configuration.NGINX R13 Features in Detail
NGINX Plus API
NGINX Plus R13 includes a new API that is unified under one single endpoint. Previous versions of NGINX Plus included separate upstream_conf and extended status APIs. The new API combines the functionality of both, and also includes a new Key-Value Store module which brings a variety of use cases for on-the-fly reconfiguration (discussed in the next section).
To enable the NGINX Plus API, use the new api directive within a location block:
server {
listen 80;
location /api {
api write=on;
}
}
By default, the NGINX Plus API provides read-only access to data. The write-on parameter enables read/write access so that changes can be made to upstream servers and the new Key-Value Store module. Access to the API should be restricted to authorized users, especially when enabled in read/write mode.
You can then see all the options available from the API endpoint by entering:
$ curl http://localhost:80/api/1/
["nginx","processes","connections","ssl","slabs","http","stream"]From there, the API can be explored by appending the corresponding item to the request URI:
nginx– general information on NGINXprocesses– information on NGINX worker processesconnections– metrics on total connectionsssl– metrics on SSL client statistics in real timeslabs– information on shared memory allocated by NGINXhttp– metrics on HTTP traffic and modify HTTP upstream configurationstream– metrics on TCP/UDP traffic and modify TCP/UDP upstream configuration
Extended Status Monitoring
NGINX Plus has more than 40 exclusive metrics on top of what’s available in the open source NGINX. You can now access these metrics using the NGINX Plus API. Use the API to access the metrics important to you.
Append connections to the request URI endpoint to output a snapshot of your connection status which includes the number of accepted, active, dropped, and idle client connections.
$ curl http://localhost:80/api/1/connections
{"accepted":3,"dropped":0,"active":1,"idle":0}Append ssl to the request URI endpoint to output a snapshot of SSL client statistics in real time.
$ curl http://localhost:80/api/1/ssl
{"handshakes":0,"handshakes_failed":0,"session_reuses":0}You can also append http/server_zones to get information on virtual servers and http/upstreams to get information on upstream groups.
On-the-Fly Reconfiguration for Upstreams
With the upstream_conf module in NGINX Plus R12 and earlier, you could dynamically reconfigure existing upstream server groups on the fly without reloading NGINX Plus. This functionality has now been incorporated into the NGINX Plus API.
Consider NGINX Plus running the following configuration:
upstream backends {
zone backends 64k;
server 10.10.10.2;
server 10.10.10.4;
}
server {
listen 80;
server_name www.example.org;
location /api {
api write=on;
}
}
There are two servers inside the backend upstream server group. With the NGINX Plus API, we can add a server to this existing upstream server group (backend) with a standard POST request using JSON text to “/api/1/http/upstreams/{upstream_server_group_name}/servers”.
$ curl -id '{"server":"10.10.10.6",}' http://localhost/api/1/http/upstreams/backend/servers
HTTP/1.1 201 Created
…Now we have reconfigured the backend upstream group, adding a server with IP address 192.168.98.77 listening on port 80.
See the documentation on the ngx_http_api_module for all information on HTTP upstream configuration options.
Key-Value Store
NGINX Plus R13 introduces a new Key-Value Store module. Key-value pairs can be created, modified, and removed using the NGINX Plus API to manage one or more “keyval” shared memory zones on the fly. The value of each key-value pair can then be evaluated as a variable for use by other NGINX features.
Use the POST, PATCH, GET, and DELETE HTTP methods to write, modify, read, and delete, respectively, key-value entries in the key-value store. The key-value store provides a wealth of on-the-fly configuration solutions to enable real-time integration with external systems.
Some example use cases include:
- Dynamic IP blacklisting
- Routing of URIs to backend server
- Managing lists of permitted URIs per user
- Managing redirect rules (see below)
The following configuration snippet uses the Key-Value Store module to manage Vanity URLs of a website.
keyval_zone zone=redirects:1M state=state/redirects.json; # Save keyvals to file
keyval $uri $target zone=redirects; # URI is the key, $target is the value
server {
listen 80;
location /api {
api write=on; # Enable the NGINX Plus API (secure this in production)
}
if ($target) { # True when $uri exists in the redirects keyval zone
return 301 $target; # Redirect client to the matching value for the $uri
}
proxy_pass http://backend;
}
The key is set to the URI from the remote machine issuing the HTTP request. If $request_uri is a key in the key-value store, the value associated with the key will be assigned to $target. If $target exists, then NGINX will redirect the client to the matching value of $uri.
To populate the key-value store with an initial vanity URL, we send the data as a JSON body to the NGINX Plus API as a POST request.
curl -id '{"/conf":"/conf2017"}' http://localhost/api/1/http/keyvals/redirects
HTTP/1.1 201 Created
…Now clients that request /conf will be redirected to /conf2017.
To see the in action, we issue a curl request to a simple app that returns the URI being requested.
$ curl -i http://localhost/conf
HTTP/1.1 301 Moved Temporarily
Location: http://localhost/conf2017More vanity URL redirects can be added to the key-value store, and existing entries can be modified on the fly.
$ curl -iX PATCH -d '{"/conf":"/conf2018"}' http://localhost/api/1/http/keyvals/redirects
HTTP/1.1 204 No Content
…You can have multiple key-value stores defined by separate shared memory zones. See the ngx_http_keyval_module documentation for more information.
Swagger Documentation
The new NGINX Plus API is provided with a Swagger specification that can be used to explore the API and understand the capabilities of each resource. The Swagger documentation is bundled with NGINX Plus and can be accessed by visiting http://nginxhost/swagger-ui/
The interactive part of the Swagger UI requires the NGINX Plus API to be enabled, which can be achieved by uncommenting the /api/ location block in the conf.d/default.conf file.
# enable /api/ location with appropriate access control in order
# to make use of NGINX Plus API
#
#location /api/ {
# api write=on;
# allow 127.0.0.1;
# deny all;
#}You can also explore the NGINX Plus API documentation at demo.nginx.com https://demo.nginx.com/swagger-ui/
Note: The entire NGINX Plus API, including the extended status metrics, upstream configuration, and the new Key-Value Store module, is exclusive to NGINX Plus.
Request Mirroring
With NGINX Plus R13, you can enable HTTP request mirroring. This feature allows you to clone HTTP requests that are proxied to an upstream group and send the cloned requests to a different destination. The original request is processed as usual, but any responses from the cloned request are ignored. There are many use cases for request mirroring, including:
- Integration with web application firewalls when deployed in learn mode, so typical request patterns can be analyzed without impacting production traffic
- Risk-free performance tuning using live, production traffic
- Duplicating file uploads on a backup server to avoid file system replication between web servers
Enabling request mirroring has negligible impact on overall system throughput and performance. The following configuration snippet shows how the new mirror directive can be used to clone a request and pass it to a separate upstream server.
location / {
mirror /mirror;
proxy_pass http://backend;
}
location /mirror {
internal;
proxy_pass http://test_backend$request_uri;
}
The original requests are proxied to the backend upstream group. Original requests are also cloned and proxied to a separate upstream group named test_backed, with the same URI as the original request.
Note: Request mirroring was initially released in open source NGINX 1.13.4.
nginScript Enhancements
Following general availability status with NGINX Plus R12, nginScript continues to be extended with core JavaScript language support. With this release, we include support for hexadecimal numbers (such as 0x7b) and scientific notations (such as 512e10). Primitive methods for the Object class have also been implemented.
nginScript now also benefits from an interactive shell to assist with the development of nginScript code.
The following shell snippet shows entry into the nginScript interactive shell and an expression to produce a random date up to 30 seconds in the future.
$ njs
interactive njscript
>> Date.now() + Math.round(Math.random()*30*1000);
1500976350968
>> 0x7b + 512e10;
5120000000123
>>Visit the intro to nginScript blog to learn more about njs.
Note: nginScript is available for both open source NGINX and NGINX Plus.
Build Tool for Dynamic Modules
NGINX 1.11.5 and NGINX Plus R11 introduced support for compiling dynamic modules independently of NGINX itself. This allows users of NGINX and NGINX Plus to use the official builds from NGINX repositories and load in the dynamic modules they need.
With NGINX Plus R13, we provide a build tool that allows dynamic modules to be compiled and packaged as an installable module that preserves and honors the dependency between it and the base NGINX version that it is linked to.
You can read about the build tool and how to package dynamic modules for production in this blog post.
Note: The build tool is available for both open source NGINX and NGINX Plus.
Sticky Learn After Headers
Session persistence is a very useful load balancing feature of NGINX Plus that lets you stick a client to a particular server. There are multiple ways to do session persistence: with sticky learn, NGINX Plus will look for the presence of a specific cookie and pin the client to the same server whenever that cookie is present.
With NGINX Plus R13 you can now establish a sticky session as soon as the upstream has sent its headers, and before the response payload, using the header directive. This allows NGINX Plus to send the sticky session to the client at the earliest opportunity.
upstream backends {
zone backends 64k;
server 10.10.10.2;
server 10.10.10.4;
sticky learn create=$upstream_cookie_sessionid
lookup=$cookie_sessionid
zone=client_sessions:1m;
header;
}
The header parameter is useful if the upstream server is prone to errors and you want the client to resend the request to the same upstream server.
Note: Sticky learn session persistence is exclusive to NGINX Plus.
Additional Features:
- HTTP trailers – NGINX Plus R13 includes the
add_trailerdirective, which allows arbitrary trailers to be added to the end of HTTP responses. The trailer response header allows the sender to include additional fields at the end of chunked messages to supply metadata that might be dynamically generated while the message body is sent, such as a message integrity check or a digital signature. - Substitutions filter dynamic modules – This community module can apply both regular expression and fixed string substitutions on response bodies. It scans the output chains buffer and matches string line by line. The substitutions module is now available as a supported dynamic module for NGINX Plus through the official NGINX Plus repository.
- Forced worker shutdown – Use the
worker_shutdown_timeoutdirective to enable a graceful shutdown of worker processes, avoiding long-lived connections of clients after restarting NGINX.
Upgrade or Try NGINX Plus
If you’re running NGINX Plus, we strongly encourage you to upgrade to Release 13 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 customer portal.
Please refer to the changes in behavior described above before proceeding with the upgrade.
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.
Extras
HTTP trailers; NGINX Plus R13 includes the add_trailer directive which allows arbitrary trailers to be added to the end of HTTP responses.
The post Announcing NGINX Plus R13 appeared first on NGINX.
Source: Announcing NGINX Plus R13
