Mercurial > hg > nginx-site
annotate xml/en/docs/http/ngx_http_slice_module.xml @ 2071:838c503fd2f7
Documented JSON object support for njs.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 14 Nov 2017 21:41:37 +0300 |
parents | 6299f9cabfe4 |
children | 4add6ae1296f |
rev | line source |
---|---|
1616
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
1 <?xml version="1.0"?> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
2 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
3 <!-- |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
4 Copyright (C) Nginx, Inc. |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
5 --> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
6 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
8 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
9 <module name="Module ngx_http_slice_module" |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
10 link="/en/docs/http/ngx_http_slice_module.html" |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
11 lang="en" |
1886
6299f9cabfe4
Changed <literal> to <value> in the slice directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1802
diff
changeset
|
12 rev="3"> |
1616
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
13 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
14 <section id="summary"> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
15 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
16 <para> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
17 The <literal>ngx_http_slice_module</literal> module (1.9.8) is a filter |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
18 that splits a request into subrequests, |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
19 each returning a certain range of response. |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
20 The filter provides more effective caching of big responses. |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
21 </para> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
22 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
23 <para> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
24 This module is not built by default, it should be enabled with the |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
25 <literal>--with-http_slice_module</literal> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
26 configuration parameter. |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
27 </para> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
28 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
29 </section> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
30 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
31 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
32 <section id="example" name="Example Configuration"> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
33 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
34 <para> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
35 <example> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
36 location / { |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
37 <emphasis>slice</emphasis> 1m; |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
38 proxy_cache cache; |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
39 proxy_cache_key $uri$is_args$args<emphasis>$slice_range</emphasis>; |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
40 proxy_set_header Range <emphasis>$slice_range</emphasis>; |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
41 proxy_cache_valid 200 206 1h; |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
42 proxy_pass http://localhost:8000; |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
43 } |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
44 </example> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
45 In this example, |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
46 the response is split into 1-megabyte cacheable slices. |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
47 </para> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
48 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
49 </section> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
50 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
51 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
52 <section id="directives" name="Directives"> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
53 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
54 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
55 <directive name="slice"> |
1886
6299f9cabfe4
Changed <literal> to <value> in the slice directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1802
diff
changeset
|
56 <syntax><value>size</value></syntax> |
1616
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
57 <default>0</default> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
58 <context>http</context> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
59 <context>server</context> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
60 <context>location</context> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
61 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
62 <para> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
63 Sets the <value>size</value> of the slice. |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
64 The zero value disables splitting responses into slices. |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
65 Note that a too low value may result in excessive memory usage |
1802
51e1c73cc027
Rephrased file descriptors in the "slice" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1616
diff
changeset
|
66 and opening a large number of files. |
1616
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
67 </para> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
68 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
69 <para> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
70 In order for a subrequest to return the required range, |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
71 the <var>$slice_range</var> variable should be |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
72 <link doc="ngx_http_proxy_module.xml" id="proxy_set_header">passed</link> to |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
73 the proxied server as the <literal>Range</literal> request header field. |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
74 If |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
75 <link doc="ngx_http_proxy_module.xml" id="proxy_cache">caching</link> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
76 is enabled, <var>$slice_range</var> should be added to the |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
77 <link doc="ngx_http_proxy_module.xml" id="proxy_cache_key">cache key</link> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
78 and caching of responses with 206 status code should be |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
79 <link doc="ngx_http_proxy_module.xml" id="proxy_cache_valid">enabled</link>. |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
80 </para> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
81 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
82 </directive> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
83 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
84 </section> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
85 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
86 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
87 <section id="variables" name="Embedded Variables"> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
88 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
89 <para> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
90 The <literal>ngx_http_slice_module</literal> module |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
91 supports the following embedded variables: |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
92 <list type="tag"> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
93 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
94 <tag-name id="var_slice_range"><var>$slice_range</var></tag-name> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
95 <tag-desc> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
96 the current slice range in |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
97 <link url="https://tools.ietf.org/html/rfc7233#section-2.1">HTTP |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
98 byte range</link> format, |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
99 for example, <literal>bytes=0-1048575</literal>. |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
100 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
101 </tag-desc> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
102 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
103 </list> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
104 </para> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
105 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
106 </section> |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
107 |
9e8ec9c67cf3
Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff
changeset
|
108 </module> |