Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_upstream_conf_module.xml @ 2846:fdf1464e1977
Moved banner to the external file to make partial rollout possible.
An idea is to have several banners and show them with different probability
specified by split directive in the nginx.conf
author | Sergey Budnevitch <sb@waeme.net> |
---|---|
date | Tue, 10 May 2022 18:07:27 +0400 |
parents | 283b1e67eaa6 |
children |
line wrap: on
line source
<?xml version="1.0"?> <!-- Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Module ngx_http_upstream_conf_module" link="/en/docs/http/ngx_http_upstream_conf_module.html" lang="en" rev="6"> <section id="summary"> <para> The <literal>ngx_http_upstream_conf_module</literal> module allows configuring upstream server groups on-the-fly via a simple HTTP interface without the need of restarting nginx. The <link doc="ngx_http_upstream_module.xml" id="zone">http</link> or <link doc="../stream/ngx_stream_upstream_module.xml" id="zone">stream</link> server group must reside in the shared memory. <note> This module was available as part of our <commercial_version>commercial subscription</commercial_version> until 1.13.10. It was superseded by the <link doc="ngx_http_api_module.xml">ngx_http_api_module</link> module in 1.13.3. </note> </para> </section> <section id="example" name="Example Configuration"> <para> <example> upstream backend { zone upstream_backend 64k; ... } server { location /upstream_conf { <emphasis>upstream_conf</emphasis>; allow 127.0.0.1; deny all; } } </example> </para> </section> <section id="directives" name="Directives"> <directive name="upstream_conf"> <syntax/> <default/> <context>location</context> <para> Turns on the HTTP interface of upstream configuration in the surrounding location. Access to this location should be <link doc="ngx_http_core_module.xml" id="satisfy">limited</link>. </para> <para> Configuration commands can be used to: <list type="bullet"> <listitem>view the group configuration;</listitem> <listitem>view, modify, or remove a server;</listitem> <listitem>add a new server.</listitem> </list> <note> 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. </note> </para> <para> A configuration command consists of parameters passed as request arguments, for example: <example> http://127.0.0.1/upstream_conf?upstream=backend </example> </para> <para> The following parameters are supported: <list type="tag" compact="no"> <tag-name> <literal>stream=</literal></tag-name> <tag-desc> Selects a <link doc="../stream/ngx_stream_upstream_module.xml">stream</link> upstream server group. Without this parameter, selects an <link doc="ngx_http_upstream_module.xml">http</link> upstream server group. </tag-desc> <tag-name> <literal>upstream=</literal><value>name</value></tag-name> <tag-desc> Selects a group to work with. This parameter is mandatory. </tag-desc> <tag-name> <literal>id=</literal><value>number</value></tag-name> <tag-desc> Selects a server for viewing, modifying, or removing. </tag-desc> <tag-name> <literal>remove=</literal></tag-name> <tag-desc> Removes a server from the group. </tag-desc> <tag-name> <literal>add=</literal></tag-name> <tag-desc> Adds a new server to the group. </tag-desc> <tag-name> <literal>backup=</literal></tag-name> <tag-desc> Required to add a backup server. <note> Before version 1.7.2, <literal>backup=</literal> was also required to view, modify, or remove existing backup servers. </note> </tag-desc> <tag-name> <literal>server=</literal><value>address</value></tag-name> <tag-desc> Same as the “<literal>address</literal>” parameter of the <link doc="ngx_http_upstream_module.xml" id="server">http</link> or <link doc="../stream/ngx_stream_upstream_module.xml" id="server">stream</link> upstream server. <para> 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 “<literal>resolver</literal>” directive in the <link doc="ngx_http_core_module.xml" id="resolver">http</link> or <link doc="../stream/ngx_stream_core_module.xml" id="resolver">stream</link> block. See also the “<literal>resolve</literal>” parameter of the <link doc="ngx_http_upstream_module.xml" id="resolve">http</link> or <link doc="../stream/ngx_stream_upstream_module.xml" id="resolve">stream</link> upstream server. </para> </tag-desc> <tag-name> <literal>service=</literal><value>name</value></tag-name> <tag-desc> Same as the “<literal>service</literal>” parameter of the <link doc="ngx_http_upstream_module.xml" id="service">http</link> or <link doc="../stream/ngx_stream_upstream_module.xml" id="service">stream</link> upstream server (1.9.13). </tag-desc> <tag-name> <literal>weight=</literal><value>number</value></tag-name> <tag-desc> Same as the “<literal>weight</literal>” parameter of the <link doc="ngx_http_upstream_module.xml" id="weight">http</link> or <link doc="../stream/ngx_stream_upstream_module.xml" id="weight">stream</link> upstream server. </tag-desc> <tag-name> <literal>max_conns=</literal><value>number</value></tag-name> <tag-desc> Same as the “<literal>max_conns</literal>” parameter of the <link doc="ngx_http_upstream_module.xml" id="max_conns">http</link> or <link doc="../stream/ngx_stream_upstream_module.xml" id="max_conns">stream</link> upstream server. </tag-desc> <tag-name> <literal>max_fails=</literal><value>number</value></tag-name> <tag-desc> Same as the “<literal>max_fails</literal>” parameter of the <link doc="ngx_http_upstream_module.xml" id="max_fails">http</link> or <link doc="../stream/ngx_stream_upstream_module.xml" id="max_fails">stream</link> upstream server. </tag-desc> <tag-name> <literal>fail_timeout=</literal><value>time</value></tag-name> <tag-desc> Same as the “<literal>fail_timeout</literal>” parameter of the <link doc="ngx_http_upstream_module.xml" id="fail_timeout">http</link> or <link doc="../stream/ngx_stream_upstream_module.xml" id="fail_timeout">stream</link> upstream server. </tag-desc> <tag-name> <literal>slow_start=</literal><value>time</value></tag-name> <tag-desc> Same as the “<literal>slow_start</literal>” parameter of the <link doc="ngx_http_upstream_module.xml" id="slow_start">http</link> or <link doc="../stream/ngx_stream_upstream_module.xml" id="slow_start">stream</link> upstream server. </tag-desc> <tag-name> <literal>down=</literal></tag-name> <tag-desc> Same as the “<literal>down</literal>” parameter of the <link doc="ngx_http_upstream_module.xml" id="down">http</link> or <link doc="../stream/ngx_stream_upstream_module.xml" id="down">stream</link> upstream server. </tag-desc> <tag-name id="drain"><literal>drain=</literal></tag-name> <tag-desc> Puts the <link doc="ngx_http_upstream_module.xml">http</link> upstream server into the “draining” mode (1.7.5). In this mode, only requests <link doc="ngx_http_upstream_module.xml" id="sticky">bound</link> to the server will be proxied to it. </tag-desc> <tag-name> <literal>up=</literal></tag-name> <tag-desc> The opposite of the “<literal>down</literal>” parameter of the <link doc="ngx_http_upstream_module.xml" id="down">http</link> or <link doc="../stream/ngx_stream_upstream_module.xml" id="down">stream</link> upstream server. </tag-desc> <tag-name> <literal>route=</literal><value>string</value></tag-name> <tag-desc> Same as the “<literal>route</literal>” parameter of the <link doc="ngx_http_upstream_module.xml" id="route">http</link> upstream server. </tag-desc> </list> 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. </para> <para> For example, to view the configuration of the whole group, send: <example> http://127.0.0.1/upstream_conf?upstream=backend </example> To view the configuration of a specific server, also specify its ID: <example> http://127.0.0.1/upstream_conf?upstream=backend&id=42 </example> </para> <para> To add a new server, specify its address in the “<literal>server=</literal>” parameter. Without other parameters specified, a server will be added with other parameters set to their default values (see the <link doc="ngx_http_upstream_module.xml" id="server">http</link> or <link doc="../stream/ngx_stream_upstream_module.xml" id="server">stream</link> “<literal>server</literal>” directive). </para> <para> For example, to add a new primary server, send: <example> http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080 </example> To add a new backup server, send: <example> http://127.0.0.1/upstream_conf?add=&upstream=backend&backup=&server=127.0.0.1:8080 </example> To add a new primary server, set its parameters to non-default values and mark it as “<literal>down</literal>”, send: <example> http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080&weight=2&down= </example> To remove a server, specify its ID: <example> http://127.0.0.1/upstream_conf?remove=&upstream=backend&id=42 </example> To mark an existing server as “<literal>down</literal>”, send: <example> http://127.0.0.1/upstream_conf?upstream=backend&id=42&down= </example> To modify the address of an existing server, send: <example> http://127.0.0.1/upstream_conf?upstream=backend&id=42&server=192.0.2.3:8123 </example> To modify other parameters of an existing server, send: <example> http://127.0.0.1/upstream_conf?upstream=backend&id=42&max_fails=3&weight=4 </example> The above examples are for an <link doc="ngx_http_upstream_module.xml">http</link> upstream server group. Similar examples for a <link doc="../stream/ngx_stream_upstream_module.xml">stream</link> upstream server group require the “<literal>stream=</literal>” parameter. </para> </directive> </section> </module>