# HG changeset patch
# User Ruslan Ermilov <ru@nginx.com>
# Date 1326478234 0
# Node ID 1fb1c077658b1056906ab7899db0fd87e1db10c9
# Parent  e00f8f8c0486a6cd1d031edfcaf49f84f73f329e
Documented the following directives: "keepalive", "proxy_http_version",
and "fastcgi_keep_conn".

diff -r e00f8f8c0486 -r 1fb1c077658b xml/en/docs/http/ngx_http_fastcgi_module.xml
--- a/xml/en/docs/http/ngx_http_fastcgi_module.xml	Fri Jan 13 18:05:01 2012 +0000
+++ b/xml/en/docs/http/ngx_http_fastcgi_module.xml	Fri Jan 13 18:10:34 2012 +0000
@@ -417,6 +417,26 @@
 </directive>
 
 
+<directive name="fastcgi_keep_conn">
+<syntax><literal>on</literal> | <literal>off</literal></syntax>
+<default>off</default>
+<context>http</context>
+<context>server</context>
+<context>location</context>
+
+<para>
+By default, a FastCGI server will close a connection right after
+sending the response.
+When set to the value <literal>on</literal>, nginx will instruct
+a FastCGI server to keep connections open.
+This in particular is necessary for 
+<link doc="ngx_http_upstream_module.xml" id="keepalive"/>
+connections to FastCGI servers to function.
+</para>
+
+</directive>
+
+
 <directive name="fastcgi_next_upstream">
 <syntax>
   <literal>error</literal> |
diff -r e00f8f8c0486 -r 1fb1c077658b xml/en/docs/http/ngx_http_proxy_module.xml
--- a/xml/en/docs/http/ngx_http_proxy_module.xml	Fri Jan 13 18:05:01 2012 +0000
+++ b/xml/en/docs/http/ngx_http_proxy_module.xml	Fri Jan 13 18:10:34 2012 +0000
@@ -372,6 +372,25 @@
 </directive>
 
 
+<directive name="proxy_http_version">
+<syntax><literal>1.0</literal> | <literal>1.1</literal></syntax>
+<default>1.0</default>
+<context>http</context>
+<context>server</context>
+<context>location</context>
+<appeared-in>1.1.4</appeared-in>
+
+<para>
+Sets the HTTP protocol version for proxying.
+By default, version 1.0 is used.
+Version 1.1 is recommended for use with
+<link doc="ngx_http_upstream_module.xml" id="keepalive"/>
+connections.
+</para>
+
+</directive>
+
+
 <directive name="proxy_ignore_client_abort">
 <syntax><literal>on</literal> | <literal>off</literal></syntax>
 <default>off</default>
diff -r e00f8f8c0486 -r 1fb1c077658b xml/en/docs/http/ngx_http_upstream_module.xml
--- a/xml/en/docs/http/ngx_http_upstream_module.xml	Fri Jan 13 18:05:01 2012 +0000
+++ b/xml/en/docs/http/ngx_http_upstream_module.xml	Fri Jan 13 18:10:34 2012 +0000
@@ -84,6 +84,126 @@
 </directive>
 
 
+<directive name="keepalive">
+<syntax><value>connections</value></syntax>
+<default/>
+<context>upstream</context>
+<appeared-in>1.1.4</appeared-in>
+
+<para>
+Activates cache of connections to upstream servers.
+</para>
+
+<para>
+The <value>connections</value> parameter sets the maximum number of
+keepalive connections to upstream servers that are retained in
+the cache per one worker process.
+If there are more idle connections to retain to an upstream than
+are specified by this number, the least recently used ones will
+be closed.
+<note>
+It should be noted that <literal>keepalive</literal> directive
+does not limit the total number of connections that nginx worker
+process can open to upstream servers.
+The new connections are always created on demand.
+The <value>connections</value> parameter should be set low enough
+to allow upstream servers to process additional new incoming
+connections as well.
+</note>
+</para>
+
+<para>
+Example configuration of memcached upstream with keepalive connections:
+<example>
+upstream memcached_backend {
+    server 127.0.0.1:11211;
+    server 10.0.0.2:11211;
+
+    keepalive 32;
+}
+
+server {
+    ...
+
+    location /memcached/ {
+        set $memcached_key $uri;
+        memcached_pass memcached_backend;
+    }
+
+}
+</example>
+</para>
+
+<para>
+For HTTP, the <link doc="ngx_http_proxy_module.xml" id="proxy_http_version"/>
+directive should be set to “<literal>1.1</literal>”
+and the <header>Connection</header> header field should be cleared:
+<example>
+upstream http_backend {
+    server 127.0.0.1:8080;
+
+    keepalive 16;
+}
+
+server {
+    ...
+
+    location /http/ {
+        proxy_pass http://http_backend;
+        proxy_http_version 1.1;
+        proxy_set_header Connection "";
+        ...
+    }
+}
+</example>
+</para>
+
+<para>
+<note>
+Alternatively, HTTP/1.0 persistent connections can be used by passing the
+<header>Connection: Keep-Alive</header> header field to an upstream server,
+though this is not recommended.
+</note>
+</para>
+
+<para>
+For FastCGI servers, it is required to set
+<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_keep_conn"/>
+for keepalive connections to work:
+<example>
+upstream fastcgi_backend {
+    server 127.0.0.1:9000;
+
+    keepalive 8;
+}
+
+server {
+    ...
+
+    location /fastcgi/ {
+        fastcgi_pass fastcgi_backend;
+        fastcgi_keep_conn on;
+        ...
+    }
+}
+</example>
+</para>
+
+<para>
+<note>
+When using load balancer modules other than the default
+round-robin, it is necessary to activate them before
+the <literal>keepalive</literal> directive.
+</note>
+
+<note>
+SCGI and uwsgi protocols do not define keepalive connections.
+</note>
+</para>
+
+</directive>
+
+
 <directive name="server">
 <syntax><value>name</value> [<value>parameters</value>]</syntax>
 <default/>
diff -r e00f8f8c0486 -r 1fb1c077658b xml/ru/docs/http/ngx_http_fastcgi_module.xml
--- a/xml/ru/docs/http/ngx_http_fastcgi_module.xml	Fri Jan 13 18:05:01 2012 +0000
+++ b/xml/ru/docs/http/ngx_http_fastcgi_module.xml	Fri Jan 13 18:10:34 2012 +0000
@@ -412,6 +412,25 @@
 
 </directive>
 
+<directive name="fastcgi_keep_conn">
+<syntax><literal>on</literal> | <literal>off</literal></syntax>
+<default>off</default>
+<context>http</context>
+<context>server</context>
+<context>location</context>
+
+<para>
+По умолчанию FastCGI-сервер будет закрывать соединение сразу же
+после отправки ответа.
+При установке значения <literal>on</literal> nginx указывает
+FastCGI-серверу оставлять соединения открытыми.
+Это в частности требуется для функционирования
+<link doc="ngx_http_upstream_module.xml" id="keepalive">постоянных
+соединений</link> с FastCGI-серверами.
+</para>
+
+</directive>
+
 
 <directive name="fastcgi_next_upstream">
 <syntax>
diff -r e00f8f8c0486 -r 1fb1c077658b xml/ru/docs/http/ngx_http_proxy_module.xml
--- a/xml/ru/docs/http/ngx_http_proxy_module.xml	Fri Jan 13 18:05:01 2012 +0000
+++ b/xml/ru/docs/http/ngx_http_proxy_module.xml	Fri Jan 13 18:10:34 2012 +0000
@@ -368,6 +368,25 @@
 </directive>
 
 
+<directive name="proxy_http_version">
+<syntax><literal>1.0</literal> | <literal>1.1</literal></syntax>
+<default>1.0</default>
+<context>http</context>
+<context>server</context>
+<context>location</context>
+<appeared-in>1.1.4</appeared-in>
+
+<para>
+Задаёт версию протокола HTTP для проксирования.
+По умолчанию используется версия 1.0.
+Для работы
+<link doc="ngx_http_upstream_module.xml" id="keepalive">постоянных
+соединений</link> рекомендуется версия 1.1.
+</para>
+
+</directive>
+
+
 <directive name="proxy_ignore_client_abort">
 <syntax><literal>on</literal> | <literal>off</literal></syntax>
 <default>off</default>
diff -r e00f8f8c0486 -r 1fb1c077658b xml/ru/docs/http/ngx_http_upstream_module.xml
--- a/xml/ru/docs/http/ngx_http_upstream_module.xml	Fri Jan 13 18:05:01 2012 +0000
+++ b/xml/ru/docs/http/ngx_http_upstream_module.xml	Fri Jan 13 18:10:34 2012 +0000
@@ -87,6 +87,126 @@
 </directive>
 
 
+<directive name="keepalive">
+<syntax><value>соединения</value></syntax>
+<default/>
+<context>upstream</context>
+<appeared-in>1.1.4</appeared-in>
+
+<para>
+Задействует кэш соединений для группы серверов.
+</para>
+
+<para>
+Параметр <value>соединения</value> устанавливает максимальное число
+постоянных соединений с серверами группы, которые будут сохраняться
+в кэше каждого рабочего процесса.
+При превышении указанного числа неактивных постоянных соединений
+с серверами группы самые старые соединения закрываются.
+<note>
+Следует отметить, что директива <literal>keepalive</literal>
+не ограничивает общее число соединений, которые рабочие процессы
+nginx могут открыть с серверами группы.
+Новые соединения всегда создаются по мере необходимости.
+Параметр <value>соединения</value> следует устанавливать
+достаточно консервативно для обеспечения возможности
+обработки серверами группы новых входящих соединений.
+</note>
+</para>
+
+<para>
+Пример конфигурации группы серверов memcached с постоянными соединениями:
+<example>
+upstream memcached_backend {
+    server 127.0.0.1:11211;
+    server 10.0.0.2:11211;
+
+    keepalive 32;
+}
+
+server {
+    ...
+
+    location /memcached/ {
+        set $memcached_key $uri;
+        memcached_pass memcached_backend;
+    }
+
+}
+</example>
+</para>
+
+<para>
+Для HTTP директиву
+<link doc="ngx_http_proxy_module.xml" id="proxy_http_version"/>
+следует установить в “<literal>1.1</literal>”,
+а строку заголовка <header>Connection</header> — очистить:
+<example>
+upstream http_backend {
+    server 127.0.0.1:8080;
+
+    keepalive 16;
+}
+
+server {
+    ...
+
+    location /http/ {
+        proxy_pass http://http_backend;
+        proxy_http_version 1.1;
+        proxy_set_header Connection "";
+        ...
+    }
+}
+</example>
+</para>
+
+<para>
+<note>
+Хоть это и не рекомендуется, но также возможно использование постоянных
+соединений в HTTP/1.0, путём передачи строки заголовка
+<header>Connection: Keep-Alive</header> серверу группы.
+</note>
+</para>
+
+<para>
+Для работы постоянных соединений с FastCGI-серверами потребуется
+включить директиву
+<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_keep_conn"/>:
+<example>
+upstream fastcgi_backend {
+    server 127.0.0.1:9000;
+
+    keepalive 8;
+}
+
+server {
+    ...
+
+    location /fastcgi/ {
+        fastcgi_pass fastcgi_backend;
+        fastcgi_keep_conn on;
+        ...
+    }
+}
+</example>
+</para>
+
+<para>
+<note>
+При использовании модулей балансировки нагрузки, отличных
+от стандартного round-robin, следует активировать их до
+директивы <literal>keepalive</literal>.
+</note>
+
+<note>
+Протоколы SCGI и uwsgi не определяют семантику постоянных соединений.
+</note>
+</para>
+
+</directive>
+
+
 <directive name="server">
 <syntax><value>название</value> [<value>параметры</value>]</syntax>
 <default/>