Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_limit_req_module.xml @ 179:8cc01e2179a9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
- Reflected recent changes made to ngx_http_limit_conn_module. - Revamped documentation for ngx_http_limit_req_module. - Translated ngx_http_limit_{conn,req}_module into English.
author Ruslan Ermilov <ru@nginx.com>
date Mon, 14 Nov 2011 18:09:03 +0000
parents
children bfe3eff81d04
comparison
equal deleted inserted replaced
178:65431179fb8f 179:8cc01e2179a9
1 <?xml version="1.0" encoding="utf-8"?>
2
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
4
5 <module name="Module ngx_http_limit_req_module"
6 link="/en/docs/http/ngx_http_limit_req_module.html"
7 lang="en">
8
9 <section id="summary">
10
11 <para>
12 The module ngx_http_limit_req_module (0.7.21) allow to limit the number
13 of requests per defined key, in particular, the number of requests
14 from a single IP address.
15 The limitation is done using the “leaky bucket” method.
16 </para>
17
18 </section>
19
20
21 <section id="example" name="Example Configuration">
22
23 <para>
24 <example>
25 http {
26 limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
27
28 ...
29
30 server {
31
32 ...
33
34 location /search/ {
35 limit_req zone=one burst=5;
36 }
37 </example>
38 </para>
39
40 </section>
41
42
43 <section id="directives" name="Directives">
44
45 <directive name="limit_req">
46 <syntax>
47 <parameter>zone</parameter>=<argument>name</argument>
48 [<parameter>burst</parameter>=<argument>number</argument>]
49 [<parameter>nodelay</parameter>]
50 </syntax>
51 <default/>
52 <context>http</context>
53 <context>server</context>
54 <context>location</context>
55
56 <para>
57 Sets a zone and the maximum allowed burst of requests.
58 If the rate of requests exceeds the rate configured for a zone,
59 request processing is delayed such as that they are processed
60 at a defined rate.
61 Excessive requests are delayed until their number exceeds the
62 defined number of bursts.
63 In this case, the request is terminated with an error
64 <http-status code="503" text="Service Temporarily Unavailable"/>.
65 By default, the number of bursts is equal to zero.
66 For example, the directives
67 <example>
68 limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
69
70 server {
71 location /search/ {
72 limit_req zone=one burst=5;
73 }
74
75 </example>
76 allow not more than 1 request per second at an average,
77 with bursts not exceeding 5 requests.
78 </para>
79
80 <para>
81 If delaying of excessive requests while requests are being limited is not
82 desired, the parameter <parameter>nodelay</parameter> should be used:
83 <example>
84 limit_req zone=one burst=5 nodelay;
85 </example>
86 </para>
87
88 </directive>
89
90
91 <directive name="limit_req_log_level">
92 <syntax>
93 <value>info</value> |
94 <value>notice</value> |
95 <value>warn</value> |
96 <value>error</value>
97 </syntax>
98 <default>error</default>
99 <context>http</context>
100 <context>server</context>
101 <context>location</context>
102 <appeared-in>0.8.18</appeared-in>
103
104 <para>
105 Sets the desired logging level for cases when the server limits
106 the number of requests, or delays request processing.
107 Delays are logged with the level one less than limits; for example,
108 if <command>limit_req_log_level notice</command> is specified,
109 delays are logged with the <value>info</value> level.
110 </para>
111
112 </directive>
113
114
115 <directive name="limit_req_zone">
116 <syntax>
117 <argument>$variable </argument>
118 <parameter>zone</parameter>=<argument>name</argument>:<argument>size </argument>
119 <parameter>rate</parameter>=<argument>rate</argument>
120 </syntax>
121 <default/>
122 <context>http</context>
123
124 <para>
125 Sets the parameters for a zone that keeps states for various keys.
126 This state stores the current number of requests in particular.
127 The key is the value of the specified variable.
128 Example usage:
129 <example>
130 limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
131 </example>
132 </para>
133
134 <para>
135 Here, the states are kept in a 10 megabyte zone “one”, and an
136 average rate of requests for this zone cannot exceed
137 1 request per second.
138 </para>
139
140 <para>
141 An IP address of the client serves as a key.
142 Note that instead of <var>$remote_addr</var>, the
143 <var>$binary_remote_addr</var> variable is used here,
144 allowing to lower the size of a state down to 64 bytes.
145 One megabyte zone can keep about 16 thousand 64-byte states.
146 If the storage for a zone is exhausted, the server will return error
147 <http-status code="503" text="Service Temporarily Unavailable"/>
148 to all further requests.
149 </para>
150
151 <para>
152 The rate is specified in requests per second (r/s).
153 If a rate of less than one request per second is desired,
154 it is specified in request per minute (r/m).
155 For example, half-request per second is 30r/m.
156 </para>
157
158 </directive>
159
160 </section>
161
162 </module>