Module ngx_http_upstream_conf_module

The ngx_http_upstream_conf_module module allows configuring upstream server groups on-the-fly via a simple HTTP interface without the need of restarting nginx. The http or stream server group must reside in the shared memory.

upstream backend {
    zone upstream_backend 64k;

    ...
}

server {
    location /upstream_conf {
        upstream_conf;
        allow 127.0.0.1;
        deny all;
    }
}

Turns on the HTTP interface of upstream configuration in the surrounding location. Access to this location should be limited.

Configuration commands can be used to:

• view the group configuration;
• view, modify, or remove a server;
• add a new server.

A configuration command consists of parameters passed as request arguments, for example:

http://127.0.0.1/upstream_conf?upstream=backend

The following parameters are supported:

stream=

Selects a stream upstream server group. Without this parameter, selects an http upstream server group.

upstream= name

Selects a group to work with. This parameter is mandatory.

id= number

Selects a server for viewing, modifying, or removing.

remove=

Removes a server from the group.

add=

Adds a new server to the group.

backup=

Required to add a backup server.

Before version 1.7.2, backup= was also required to view, modify, or remove existing backup servers.

server= address

Same as the “ address” parameter of the http or stream upstream server.

When adding a server, it is possible to specify it as a domain name. In this case, changes of the IP addresses that correspond to a domain name will be monitored and automatically applied to the upstream configuration without the need of restarting nginx (1.7.2). This requires the “resolver” directive in the http or stream block. See also the “resolve” parameter of the http or stream upstream server.

service= name

Same as the “ service” parameter of the http or stream upstream server (1.9.13).

weight= number

Same as the “ weight” parameter of the http or stream upstream server.

max_conns= number

Same as the “ max_conns” parameter of the http or stream upstream server.

max_fails= number

Same as the “ max_fails” parameter of the http or stream upstream server.

fail_timeout= time

Same as the “ fail_timeout” parameter of the http or stream upstream server.

slow_start= time

Same as the “ slow_start” parameter of the http or stream upstream server.

down=

Same as the “ down” parameter of the http or stream upstream server.

drain=

Puts the http upstream server into the “draining” mode (1.7.5). In this mode, only requests bound to the server will be proxied to it.

up=

The opposite of the “ down” parameter of the http or stream upstream server.

route= string

Same as the “ route” parameter of the http upstream server.

The first three parameters select an object. This can be either the whole http or stream upstream server group, or a specific server. Without other parameters, the configuration of the selected group or server is shown.

For example, to view the configuration of the whole group, send:

http://127.0.0.1/upstream_conf?upstream=backend

To view the configuration of a specific server, also specify its ID:

http://127.0.0.1/upstream_conf?upstream=backend&id=42

To add a new server, specify its address in the “server=” parameter. Without other parameters specified, a server will be added with other parameters set to their default values (see the http or stream “server” directive).

For example, to add a new primary server, send:

http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080

To add a new backup server, send:

http://127.0.0.1/upstream_conf?add=&upstream=backend&backup=&server=127.0.0.1:8080

To add a new primary server, set its parameters to non-default values and mark it as “down”, send:

http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080&weight=2&down=

To remove a server, specify its ID:

http://127.0.0.1/upstream_conf?remove=&upstream=backend&id=42

To mark an existing server as “down”, send:

http://127.0.0.1/upstream_conf?upstream=backend&id=42&down=

To modify the address of an existing server, send:

http://127.0.0.1/upstream_conf?upstream=backend&id=42&server=192.0.2.3:8123

To modify other parameters of an existing server, send:

http://127.0.0.1/upstream_conf?upstream=backend&id=42&max_fails=3&weight=4

The above examples are for an http upstream server group. Similar examples for a stream upstream server group require the “stream=” parameter.