Mercurial > hg > nginx-site

annotate xml/en/docs/http/ngx_http_upstream_hc_module.xml @ 2632:52500ccb82c1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated docs for the upcoming NGINX Plus release.
author Yaroslav Zhuravlev <yar@nginx.com>
date Fri, 04 Dec 2020 13:34:05 +0000
parents d5e576eb7677
children efb3d27dfa23
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
293
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
1 <?xml version="1.0"?>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
2
580
be54c443235a Added copyright markers to documentation sources.
Ruslan Ermilov <ru@nginx.com>
parents: 566
diff changeset
3 <!--
be54c443235a Added copyright markers to documentation sources.
Ruslan Ermilov <ru@nginx.com>
parents: 566
diff changeset
4 Copyright (C) Nginx, Inc.
be54c443235a Added copyright markers to documentation sources.
Ruslan Ermilov <ru@nginx.com>
parents: 566
diff changeset
5 -->
be54c443235a Added copyright markers to documentation sources.
Ruslan Ermilov <ru@nginx.com>
parents: 566
diff changeset
6
293
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
8
1945
88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1925
diff changeset
9 <module name="Module ngx_http_upstream_hc_module"
88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1925
diff changeset
10 link="/en/docs/http/ngx_http_upstream_hc_module.html"
589
764fbac1b8b4 Added document revision.
Ruslan Ermilov <ru@nginx.com>
parents: 580
diff changeset
11 lang="en"
2359
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
12 rev="5">
293
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
13
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
14 <section id="summary">
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
15
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
16 <para>
1945
88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1925
diff changeset
17 The <literal>ngx_http_upstream_hc_module</literal> module
88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1925
diff changeset
18 allows enabling periodic health checks of the servers in a
88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1925
diff changeset
19 <link doc="ngx_http_upstream_module.xml" id="upstream">group</link>
88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1925
diff changeset
20 referenced in the surrounding location.
1946
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
21 The server group must reside in the
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
22 <link doc="ngx_http_upstream_module.xml" id="zone">shared memory</link>.
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
23 </para>
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
24
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
25 <para>
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
26 If a health check fails,
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
27 the server will be considered unhealthy.
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
28 If several health checks are defined for the same group of servers,
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
29 a single failure of any check will make the corresponding server be
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
30 considered unhealthy.
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
31 Client requests are not passed to unhealthy servers
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
32 and servers in the “checking” state.
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
33 </para>
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
34
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
35 <para>
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
36 <note>
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
37 Please note that most of the variables will have empty values
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
38 when used with health checks.
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
39 </note>
1945
88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1925
diff changeset
40 </para>
88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1925
diff changeset
41
88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1925
diff changeset
42 <para>
88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1925
diff changeset
43 <note>
88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1925
diff changeset
44 This module is available as part of our
88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1925
diff changeset
45 <commercial_version>commercial subscription</commercial_version>.
88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1925
diff changeset
46 </note>
293
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
47 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
48
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
49 </section>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
50
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
51
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
52 <section id="example" name="Example Configuration">
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
53
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
54 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
55 <example>
1945
88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1925
diff changeset
56 upstream dynamic {
1259
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes.
Ruslan Ermilov <ru@nginx.com>
parents: 1241
diff changeset
57 zone upstream_dynamic 64k;
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
58
1259
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes.
Ruslan Ermilov <ru@nginx.com>
parents: 1241
diff changeset
59 server backend1.example.com weight=5;
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes.
Ruslan Ermilov <ru@nginx.com>
parents: 1241
diff changeset
60 server backend2.example.com:8080 fail_timeout=5s slow_start=30s;
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
61 server 192.0.2.1 max_fails=3;
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
62
1259
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes.
Ruslan Ermilov <ru@nginx.com>
parents: 1241
diff changeset
63 server backup1.example.com:8080 backup;
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes.
Ruslan Ermilov <ru@nginx.com>
parents: 1241
diff changeset
64 server backup2.example.com:8080 backup;
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
65 }
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
66
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
67 server {
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
68 location / {
1945
88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1925
diff changeset
69 proxy_pass http://dynamic;
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
70 health_check;
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
71 }
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
72 }
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
73 </example>
1946
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
74 With this configuration, nginx will send “<literal>/</literal>” requests to each
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
75 server in the <literal>backend</literal> group every five seconds.
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
76 If any communication error or timeout occurs, or a
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
77 proxied server responds with the status code other than
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
78 2xx or 3xx, the health check will fail, and the server will
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
79 be considered unhealthy.
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
80 </para>
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
81
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
82 <para>
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
83 Health checks can be configured to test the status code of a response,
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
84 presence of certain header fields and their values,
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
85 and the body contents.
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
86 Tests are configured separately using the <link id="match"/> directive
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
87 and referenced in the <literal>match</literal> parameter
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
88 of the <link id="health_check"/> directive:
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
89 <example>
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
90 http {
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
91 server {
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
92 ...
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
93 location / {
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
94 proxy_pass http://backend;
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
95 health_check match=welcome;
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
96 }
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
97 }
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
98
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
99 match welcome {
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
100 status 200;
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
101 header Content-Type = text/html;
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
102 body ~ "Welcome to nginx!";
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
103 }
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
104 }
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
105 </example>
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
106 This configuration shows that in order for a health check to pass, the response
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
107 to a health check request should succeed, have status 200,
37df1535ea91 Moved info from http "health_check" and "match" to intro.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1945
diff changeset
108 and contain “<literal>Welcome to nginx!</literal>” in the body.
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
109 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
110
293
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
111 </section>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
112
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
113
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
114 <section id="directives" name="Directives">
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
115
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
116 <directive name="health_check">
1241
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
117 <syntax>[<value>parameters</value>]</syntax>
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
118 <default/>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
119 <context>location</context>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
120
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
121 <para>
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 955
diff changeset
122 Enables periodic health checks of the servers in a
1945
88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1925
diff changeset
123 <link doc="ngx_http_upstream_module.xml" id="upstream">group</link>
88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1925
diff changeset
124 referenced in the surrounding location.
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
125 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
126
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
127 <para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
128 The following optional parameters are supported:
1241
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
129 <list type="tag">
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
130
1949
8f9c685dfabd Updated IDs in "health_check" directives.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1946
diff changeset
131 <tag-name id="health_check_interval">
1241
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
132 <literal>interval</literal>=<value>time</value>
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
133 </tag-name>
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
134 <tag-desc>
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 955
diff changeset
135 sets the interval between two consecutive health checks,
1891
6225d50b3cba Replaced semicolon with dot in health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1866
diff changeset
136 by default, 5 seconds.
1241
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
137 </tag-desc>
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
138
1866
6f2c5a36b4d1 Documented the "jitter" parameter for health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1854
diff changeset
139 <tag-name id="health_check_jitter">
6f2c5a36b4d1 Documented the "jitter" parameter for health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1854
diff changeset
140 <literal>jitter</literal>=<value>time</value>
6f2c5a36b4d1 Documented the "jitter" parameter for health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1854
diff changeset
141 </tag-name>
6f2c5a36b4d1 Documented the "jitter" parameter for health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1854
diff changeset
142 <tag-desc>
6f2c5a36b4d1 Documented the "jitter" parameter for health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1854
diff changeset
143 sets the time within which
6f2c5a36b4d1 Documented the "jitter" parameter for health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1854
diff changeset
144 each health check will be randomly delayed,
1891
6225d50b3cba Replaced semicolon with dot in health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1866
diff changeset
145 by default, there is no delay.
1866
6f2c5a36b4d1 Documented the "jitter" parameter for health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1854
diff changeset
146 </tag-desc>
6f2c5a36b4d1 Documented the "jitter" parameter for health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1854
diff changeset
147
1949
8f9c685dfabd Updated IDs in "health_check" directives.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1946
diff changeset
148 <tag-name id="health_check_fails">
1241
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
149 <literal>fails</literal>=<value>number</value>
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
150 </tag-name>
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
151 <tag-desc>
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 955
diff changeset
152 sets the number of consecutive failed health checks of a particular server
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 955
diff changeset
153 after which this server will be considered unhealthy,
1891
6225d50b3cba Replaced semicolon with dot in health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1866
diff changeset
154 by default, 1.
1241
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
155 </tag-desc>
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
156
1949
8f9c685dfabd Updated IDs in "health_check" directives.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1946
diff changeset
157 <tag-name id="health_check_passes">
1241
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
158 <literal>passes</literal>=<value>number</value>
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
159 </tag-name>
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
160 <tag-desc>
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 955
diff changeset
161 sets the number of consecutive passed health checks of a particular server
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
162 after which the server will be considered healthy,
1891
6225d50b3cba Replaced semicolon with dot in health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1866
diff changeset
163 by default, 1.
1241
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
164 </tag-desc>
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
165
1949
8f9c685dfabd Updated IDs in "health_check" directives.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1946
diff changeset
166 <tag-name id="health_check_uri">
1241
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
167 <literal>uri</literal>=<value>uri</value>
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
168 </tag-name>
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
169 <tag-desc>
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
170 defines the URI used in health check requests,
1891
6225d50b3cba Replaced semicolon with dot in health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1866
diff changeset
171 by default, “<literal>/</literal>”.
1241
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
172 </tag-desc>
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
173
1925
a58b35cc0823 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1891
diff changeset
174 <tag-name id="health_check_mandatory">
a58b35cc0823 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1891
diff changeset
175 <literal>mandatory</literal>
a58b35cc0823 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1891
diff changeset
176 </tag-name>
a58b35cc0823 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1891
diff changeset
177 <tag-desc>
a58b35cc0823 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1891
diff changeset
178 sets the initial “checking” state for a server
a58b35cc0823 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1891
diff changeset
179 until the first health check is completed (1.11.7).
1950
ef22a80a2696 Described the "checking" state in "health_check mandatory"
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1949
diff changeset
180 Client requests are not passed to servers in the “checking” state.
1925
a58b35cc0823 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1891
diff changeset
181 If the parameter is not specified,
a58b35cc0823 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1891
diff changeset
182 the server will be initially considered healthy.
a58b35cc0823 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1891
diff changeset
183 </tag-desc>
a58b35cc0823 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1891
diff changeset
184
1949
8f9c685dfabd Updated IDs in "health_check" directives.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1946
diff changeset
185 <tag-name id="health_check_match">
1241
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
186 <literal>match</literal>=<value>name</value>
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
187 </tag-name>
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
188 <tag-desc>
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 955
diff changeset
189 specifies the <literal>match</literal> block configuring the tests that a
1891
6225d50b3cba Replaced semicolon with dot in health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1866
diff changeset
190 response should pass in order for a health check to pass.
6225d50b3cba Replaced semicolon with dot in health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1866
diff changeset
191 By default, the response should have status code 2xx or 3xx.
1636
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1625
diff changeset
192 </tag-desc>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1625
diff changeset
193
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1625
diff changeset
194 <tag-name id="health_check_port">
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1625
diff changeset
195 <literal>port</literal>=<value>number</value>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1625
diff changeset
196 </tag-name>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1625
diff changeset
197 <tag-desc>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1625
diff changeset
198 defines the port used when connecting to a server
1891
6225d50b3cba Replaced semicolon with dot in health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1866
diff changeset
199 to perform a health check (1.9.7).
1945
88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1925
diff changeset
200 By default, equals the
88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1925
diff changeset
201 <link doc="ngx_http_upstream_module.xml" id="server"/> port.
1241
2246339a6a93 Upstream: added IDs for "server" and "health_check" params.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1236
diff changeset
202 </tag-desc>
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
203
2632
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
204 <tag-name id="health_check_grpc">
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
205 <literal>type</literal>=<literal>grpc</literal>
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
206 [<literal>grpc_service</literal>=<value>name</value>]
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
207 [<literal>grpc_status</literal>=<value>code</value>]
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
208 </tag-name>
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
209 <tag-desc>
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
210 enables periodic
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
211 <link url="https://github.com/grpc/grpc/blob/master/doc/health-checking.md#grpc-health-checking-protocol">health
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
212 checks</link> of a gRPC server
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
213 or a particular gRPC service specified with the optional
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
214 <literal>grpc_service</literal> parameter (1.19.5).
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
215 If the server does not support the gRPC Health Checking Protocol,
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
216 the optional <literal>grpc_status</literal> parameter can be used
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
217 to specify non-zero gRPC
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
218 <link url="https://github.com/grpc/grpc/blob/master/doc/statuscodes.md#status-codes-and-their-use-in-grpc">status</link>
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
219 (for example,
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
220 status code “<literal>12</literal>” / “<literal>UNIMPLEMENTED</literal>”)
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
221 that will be treated as healthy:
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
222 <example>
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
223 health_check mandatory type=grpc grpc_status=12;
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
224 </example>
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
225 The <literal>type</literal>=<literal>grpc</literal> parameter
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
226 must be specified after all other directive parameters,
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
227 <literal>grpc_service</literal> and <literal>grpc_status</literal>
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
228 must follow <literal>type</literal>=<literal>grpc</literal>.
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
229 The parameter is not compatible with
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
230 <link id="health_check_uri"><literal>uri</literal></link> or
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
231 <link id="health_check_match"><literal>match</literal></link> parameters.
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
232 </tag-desc>
52500ccb82c1 Updated docs for the upcoming NGINX Plus release.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2359
diff changeset
233
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
234 </list>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
235 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
236
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
237 </directive>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
238
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
239
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
240 <directive name="match">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
241 <syntax block="yes"><value>name</value></syntax>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
242 <default/>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
243 <context>http</context>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
244
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
245 <para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
246 Defines the named test set used to verify responses to health check requests.
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
247 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
248
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
249 <para>
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 955
diff changeset
250 The following items can be tested in a response:
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
251 <list type="tag">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
252
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
253 <tag-name><literal>status 200;</literal></tag-name>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
254 <tag-desc>status is 200</tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
255
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
256 <tag-name><literal>status ! 500;</literal></tag-name>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
257 <tag-desc>status is not 500</tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
258
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
259 <tag-name><literal>status 200 204;</literal></tag-name>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
260 <tag-desc>status is 200 or 204</tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
261
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
262 <tag-name><literal>status ! 301 302;</literal></tag-name>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
263 <tag-desc>status is neither 301 nor 302</tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
264
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
265 <tag-name><literal>status 200-399;</literal></tag-name>
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 962
diff changeset
266 <tag-desc>status is in the range from 200 to 399</tag-desc>
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
267
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
268 <tag-name><literal>status ! 400-599;</literal></tag-name>
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 962
diff changeset
269 <tag-desc>status is not in the range from 400 to 599</tag-desc>
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
270
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
271 <tag-name><literal>status 301-303 307;</literal></tag-name>
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 955
diff changeset
272 <tag-desc>status is either 301, 302, 303, or 307</tag-desc>
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
273
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
274 </list>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
275
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
276 <list type="tag">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
277
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
278 <tag-name><literal>header Content-Type = text/html;</literal></tag-name>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
279 <tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
280 header contains <header>Content-Type</header>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
281 with value <literal>text/html</literal>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
282 </tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
283
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
284 <tag-name><literal>header Content-Type != text/html;</literal></tag-name>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
285 <tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
286 header contains <header>Content-Type</header>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
287 with value other than <literal>text/html</literal>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
288 </tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
289
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
290 <tag-name><literal>header Connection ~ close;</literal></tag-name>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
291 <tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
292 header contains <header>Connection</header>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
293 with value matching regular expression <literal>close</literal>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
294 </tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
295
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
296 <tag-name><literal>header Connection !~ close;</literal></tag-name>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
297 <tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
298 header contains <header>Connection</header>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
299 with value not matching regular expression <literal>close</literal>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
300 </tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
301
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
302 <tag-name><literal>header Host;</literal></tag-name>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
303 <tag-desc>header contains <header>Host</header></tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
304
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
305 <tag-name><literal>header ! X-Accel-Redirect;</literal></tag-name>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
306 <tag-desc>header lacks <header>X-Accel-Redirect</header></tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
307
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
308 </list>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
309
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
310 <list type="tag">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
311
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
312 <tag-name><literal>body ~ "Welcome to nginx!";</literal></tag-name>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
313 <tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
314 body matches regular expression “<literal>Welcome to nginx!</literal>”
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
315 </tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
316
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
317 <tag-name><literal>body !~ "Welcome to nginx!";</literal></tag-name>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
318 <tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
319 body does not match regular expression “<literal>Welcome to nginx!</literal>”
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
320 </tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
321
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
322 </list>
2359
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
323
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
324 <list type="tag">
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
325
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
326 <tag-name id="match_require"><literal>require</literal>
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
327 <value>$variable</value>
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
328 <literal>...;</literal></tag-name>
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
329 <tag-desc>
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
330 all specified variables are not empty and not equal to “0” (1.15.9).
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
331 </tag-desc>
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
332
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
333 </list>
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
334 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
335
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
336 <para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
337 If several tests are specified,
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 955
diff changeset
338 the response matches only if it matches all tests.
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
339 <note>
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 955
diff changeset
340 Only the first 256k of the response body are examined.
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
341 </note>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
342 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
343
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
344 <para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
345 Examples:
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
346 <example>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
347 # status is 200, content type is "text/html",
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
348 # and body contains "Welcome to nginx!"
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
349 match welcome {
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
350 status 200;
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
351 header Content-Type = text/html;
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
352 body ~ "Welcome to nginx!";
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
353 }
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
354 </example>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
355
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
356 <example>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
357 # status is not one of 301, 302, 303, or 307, and header does not have "Refresh:"
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
358 match not_redirect {
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
359 status ! 301-303 307;
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
360 header ! Refresh;
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
361 }
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
362 </example>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
363
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
364 <example>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
365 # status ok and not in maintenance mode
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
366 match server_ok {
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
367 status 200-399;
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
368 body !~ "maintenance mode";
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
369 }
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
370 </example>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
371
2359
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
372 <example>
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
373 # status is 200 or 204
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
374 map $upstream_status $good_status {
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
375 200 1;
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
376 204 1;
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
377 }
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
378
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
379 match server_ok {
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
380 require $good_status;
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
381 }
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
382 </example>
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1950
diff changeset
383
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
384 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents: 942
diff changeset
385
1026
3056640d5022 Upstream: documented new "sticky" features.
Ruslan Ermilov <ru@nginx.com>
parents: 1011
diff changeset
386 </directive>
3056640d5022 Upstream: documented new "sticky" features.
Ruslan Ermilov <ru@nginx.com>
parents: 1011
diff changeset
387
293
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
388 </section>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
389
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
390 </module>