Mercurial > hg > nginx-site
diff xml/en/docs/http/ngx_http_slice_module.xml @ 1616:9e8ec9c67cf3
Documented ngx_http_slice_module.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 08 Dec 2015 18:53:15 +0300 |
parents | |
children | 51e1c73cc027 |
line wrap: on
line diff
new file mode 100644 --- /dev/null +++ b/xml/en/docs/http/ngx_http_slice_module.xml @@ -0,0 +1,108 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_http_slice_module" + link="/en/docs/http/ngx_http_slice_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The <literal>ngx_http_slice_module</literal> module (1.9.8) is a filter +that splits a request into subrequests, +each returning a certain range of response. +The filter provides more effective caching of big responses. +</para> + +<para> +This module is not built by default, it should be enabled with the +<literal>--with-http_slice_module</literal> +configuration parameter. +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +location / { + <emphasis>slice</emphasis> 1m; + proxy_cache cache; + proxy_cache_key $uri$is_args$args<emphasis>$slice_range</emphasis>; + proxy_set_header Range <emphasis>$slice_range</emphasis>; + proxy_cache_valid 200 206 1h; + proxy_pass http://localhost:8000; +} +</example> +In this example, +the response is split into 1-megabyte cacheable slices. +</para> + +</section> + + +<section id="directives" name="Directives"> + + +<directive name="slice"> +<syntax><literal>size</literal></syntax> +<default>0</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Sets the <value>size</value> of the slice. +The zero value disables splitting responses into slices. +Note that a too low value may result in excessive memory usage +and a large number of file descriptors. +</para> + +<para> +In order for a subrequest to return the required range, +the <var>$slice_range</var> variable should be +<link doc="ngx_http_proxy_module.xml" id="proxy_set_header">passed</link> to +the proxied server as the <literal>Range</literal> request header field. +If +<link doc="ngx_http_proxy_module.xml" id="proxy_cache">caching</link> +is enabled, <var>$slice_range</var> should be added to the +<link doc="ngx_http_proxy_module.xml" id="proxy_cache_key">cache key</link> +and caching of responses with 206 status code should be +<link doc="ngx_http_proxy_module.xml" id="proxy_cache_valid">enabled</link>. +</para> + +</directive> + +</section> + + +<section id="variables" name="Embedded Variables"> + +<para> +The <literal>ngx_http_slice_module</literal> module +supports the following embedded variables: +<list type="tag"> + +<tag-name id="var_slice_range"><var>$slice_range</var></tag-name> +<tag-desc> +the current slice range in +<link url="https://tools.ietf.org/html/rfc7233#section-2.1">HTTP +byte range</link> format, +for example, <literal>bytes=0-1048575</literal>. + +</tag-desc> + +</list> +</para> + +</section> + +</module>