Module ngx_http_upstream_conf_module
Example Configuration Directives upstream_conf |
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.
This module was superseded by the ngx_http_api_module module in 1.13.0.
This module is available as part of our commercial subscription.
Example Configuration
upstream backend { zone upstream_backend 64k; ... } server { location /upstream_conf { upstream_conf; allow 127.0.0.1; deny all; } }
Directives
Syntax: |
upstream_conf; |
---|---|
Default: | — |
Context: |
location |
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.
Since addresses in a group are not required to be unique, specific servers in a group are referenced by their IDs. IDs are assigned automatically and shown when adding a new server or viewing the group configuration.
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.