22/9/2015

OntheFlyReconfigurationofNGINXPlus|NGINX

ON-THE-FLY
RECONFIGURATION OF
NGINX PLUS
Web infrastructures hosted in the Amazon Elastic Compute Cloud (EC2) and other virtual platforms
change rapidly. Self-discovering configurations are becoming necessary, and NGINXs
configuration file-based approach is not always flexible and open enough when you automate
heavily, when you use autoscaling, or when you deploy updates by rebuilding servers rather than
patching existing ones in place.
With NGINXPlus, you can reconfigure load-balanced server groups (both HTTP and TCP) on the fly
using the Domain Name System (DNS) or a simple HTTP interface.

Configuring Load Balancing using DNS

Normally, NGINX resolves DNS names when it starts up, and caches these resolved values
https://www.nginx.com/products/ontheflyreconfiguration/

1/7

22/9/2015

OntheFlyReconfigurationofNGINXPlus|NGINX

persistently. When you use a domain name (like api.u.com in the following example) to identify a
group of upstream servers in the server directive and include the resolve parameter, NGINXPlus
periodically re-resolves the name in DNS. If the associated list of IP addresses has changed,
NGINXPlus immediately starts load balancing across the updated group of servers. (You must also
include the resolver directive in the configuration, as shown.) Using DNS to publish the identities of
upstream servers in this way is ideal for organizations that frequently need to change the
configuration of upstream server groups, such as those that use auto-scaling.

Free Trial

Contact Sales

Products
NGINX Plus
Technical Specifications
Compareis
Versions
The benefit
that DevOps staff can manage the servers in the upstream group without modifying
Price & Buy
the NGINXPlus configuration directly.
NGINX Plus for AWS
NGINX Plus for Azure
Solutions
Load Balancing
Web Server
To use
on-the-fly
Streaming
Mediareconfiguration, you need to grant secured access to the upstream_conf handler.
& Mobile Acceleration
This Web
is a special
handler that can be configured to inspect and reconfigure upstream groups in
Application Security
NGINXPlus:
API Gateway
Application Delivery Controller

3
On-the-Fly
Reconfiguration of Upstream Server Groups

https://www.nginx.com/products/ontheflyreconfiguration/

2/7

22/9/2015

OntheFlyReconfigurationofNGINXPlus|NGINX

Resources
Admin Guide
upstream_conf;
Library
Webinars
allow127.0.0.1;#permitaccessfromlocalhost
Community Resources
denyall;#denyaccessfromeverywhereelse
FAQ
}
Support & Services
Support
Professional
Services
You must
also configure
a shared memory zone for the upstream servers with the zone directive:
Training
Company
About Us
upstreambackend{
Careers
zonebackend64k;
Partners
#...
} Leadership
Press
Customers
AnBlog
HTTP GET for the named group returns its current configuration:
location/upstream_conf{

S 1-800-915-9122
U
k

Login
$curlhttp://localhost/upstream_conf?upstream=backend
server192.168.56.101:80;#id=0
server192.168.56.102:80;#id=1
server192.168.56.103:80;#id=2

You can use the upstream_conf handler to add or remove servers, dynamically alter their weights,
and set their status as primary, backup, or down.
https://www.nginx.com/products/ontheflyreconfiguration/

3/7

22/9/2015

OntheFlyReconfigurationofNGINXPlus|NGINX

This capability provides a straightforward way for servers to signal their status to NGINXPlus. For
example:
When a server in an autoscaled server farm starts up, it can add itself to a named upstream
group. When the server shuts down, it can cleanly remove itself from the group.
You can dynamically alter the weight for each server. For example, if a server is about to run a
backup or large batch job, it can signal NGINXPlus to reduce the load sent to it; requests pinned
to that server by session persistence continue, but new connections are throttled back.
You can also use this feature to help orchestrate simple management operations, such as
temporarily draining sessions from a running server before performing a software update:

$curlhttp://localhost/upstream_conf?upstream=backend\&id=1\&drain=1
server192.168.56.102:80;#id=1draining
$curlhttp://localhost/upstream_conf?upstream=backend
server192.168.56.101:80;#id=0
server192.168.56.102:80;#id=1draining
server192.168.56.103:80;#id=2

Note that changes committed through the upstream_conf interface do not persist across
NGINXPlus restarts or configuration reloads, so they must be reapplied or regarded as transient.
For more details on the parameters you can configure, see the reference documentation for
https://www.nginx.com/products/ontheflyreconfiguration/

4/7

22/9/2015

OntheFlyReconfigurationofNGINXPlus|NGINX

upstream server groups.

The Web Server, Reinvented

Powering 1 in 3 of the world's busiest sites, NGINX is the secret heart of the modern
web.

LEARN MORE

ABOUT NGINX

NGINX, Inc. provides products, solutions, and services for its renowned open source software, NGINX. Run by the busiest
web sites on the Internet, NGINX enables high performance web architecture to improve user experience, without incurring
unnecessary costs in capital or time.

https://www.nginx.com/products/ontheflyreconfiguration/

5/7

22/9/2015

OntheFlyReconfigurationofNGINXPlus|NGINX

1
1

TRY NGINX PLUS FOR FREE

ASK US A QUESTION

Sign up for newsletter

Products

Solutions

Resources

Company

NGINX Plus

Load Balancing

Admin Guide

About Us

Compare Versions

Web Server

Webinars

Careers

Price & Buy

Streaming Media

Community Resources

Partners

NGINX Plus Technical

Specifications

Web & Mobile Acceleration FAQ

Leadership

Application Security

Press

NGINX Plus for AWS

API Gateway

NGINX Plus for Microsoft

Azure

Support & Services

Support
Professional Services
Training

Customers
Blog

FTL R
Connect With Us

https://www.nginx.com/products/ontheflyreconfiguration/

6/7

22/9/2015

OntheFlyReconfigurationofNGINXPlus|NGINX

Stay in the Loop

enter your email

NGINX Inc. 85 Federal St. San Francisco, CA 94107 1-800-915-9122 Privacy Policy

https://www.nginx.com/products/ontheflyreconfiguration/

7/7