Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_upstream_conf_module.xml @ 2326:5d045e964270
Moved the repository introduction paragraph to an appropriate place.
author | Konstantin Pavlov <thresh@videolan.org> |
---|---|
date | Wed, 30 Jan 2019 13:05:02 +0300 |
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>