# HG changeset patch
# User Yaroslav Zhuravlev <yar@nginx.com>
# Date 1474479976 -10800
# Node ID 59d1f512c3a0a12736511a4497f8b2a5029841a6
# Parent  be868c8f6e9c94bf27922e2e135face941c3330d
Documented the ngx_stream_ssl_preread_module module.

diff --git a/xml/en/GNUmakefile b/xml/en/GNUmakefile
--- a/xml/en/GNUmakefile
+++ b/xml/en/GNUmakefile
@@ -107,6 +107,7 @@ REFS =									\
 		stream/ngx_stream_return_module				\
 		stream/ngx_stream_split_clients_module			\
 		stream/ngx_stream_ssl_module				\
+		stream/ngx_stream_ssl_preread_module			\
 		stream/ngx_stream_upstream_module			\
 		stream/stream_processing				\
 
diff --git a/xml/en/docs/index.xml b/xml/en/docs/index.xml
--- a/xml/en/docs/index.xml
+++ b/xml/en/docs/index.xml
@@ -8,7 +8,7 @@
 <article name="nginx documentation"
          link="/en/docs/"
          lang="en"
-         rev="33"
+         rev="34"
          toc="no">
 
 
@@ -555,6 +555,11 @@ ngx_stream_ssl_module</link>
 </listitem>
 
 <listitem>
+<link doc="stream/ngx_stream_ssl_preread_module.xml">
+ngx_stream_ssl_preread_module</link>
+</listitem>
+
+<listitem>
 <link doc="stream/ngx_stream_upstream_module.xml">
 ngx_stream_upstream_module</link>
 </listitem>
diff --git a/xml/en/docs/stream/ngx_stream_core_module.xml b/xml/en/docs/stream/ngx_stream_core_module.xml
--- a/xml/en/docs/stream/ngx_stream_core_module.xml
+++ b/xml/en/docs/stream/ngx_stream_core_module.xml
@@ -9,7 +9,7 @@
 <module name="Module ngx_stream_core_module"
         link="/en/docs/stream/ngx_stream_core_module.html"
         lang="en"
-        rev="20">
+        rev="21">
 
 <section id="summary">
 
@@ -235,6 +235,36 @@ Different servers must listen on differe
 </directive>
 
 
+<directive name="preread_buffer_size">
+<syntax><value>size</value></syntax>
+<default>16k</default>
+<context>stream</context>
+<context>server</context>
+<appeared-in>1.11.5</appeared-in>
+
+<para>
+Specifies a <value>size</value> of the
+<link doc="stream_processing.xml" id="preread_phase">preread</link> buffer.
+</para>
+
+</directive>
+
+
+<directive name="preread_timeout">
+<syntax><value>timeout</value></syntax>
+<default>30s</default>
+<context>stream</context>
+<context>server</context>
+<appeared-in>1.11.5</appeared-in>
+
+<para>
+Specifies a <value>timeout</value> of the
+<link doc="stream_processing.xml" id="preread_phase">preread</link> phase.
+</para>
+
+</directive>
+
+
 <directive name="proxy_protocol_timeout">
 <syntax><value>timeout</value></syntax>
 <default>30s</default>
diff --git a/xml/en/docs/stream/ngx_stream_ssl_preread_module.xml b/xml/en/docs/stream/ngx_stream_ssl_preread_module.xml
new file mode 100644
--- /dev/null
+++ b/xml/en/docs/stream/ngx_stream_ssl_preread_module.xml
@@ -0,0 +1,95 @@
+<?xml version="1.0"?>
+
+<!--
+  Copyright (C) Nginx, Inc.
+  -->
+
+<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
+
+<module name="Module ngx_stream_ssl_preread_module"
+        link="/en/docs/stream/ngx_stream_ssl_preread_module.html"
+        lang="en"
+        rev="1">
+
+<section id="summary">
+
+<para>
+The <literal>ngx_stream_ssl_preread_module</literal> module (1.11.5) allows
+extracting information from the
+<link url="https://tools.ietf.org/html/rfc5246#section-7.4.1.2">ClientHello</link>
+message without terminating SSL/TLS,
+for example, the sever name requested through
+<link url="https://tools.ietf.org/html/rfc6066#section-3">SNI</link>.
+This module is not built by default, it should be enabled with the
+<literal>--with-stream_ssl_preread_module</literal>
+configuration parameter.
+</para>
+
+</section>
+
+
+<section id="example" name="Example Configuration">
+
+<para>
+<example>
+map $ssl_preread_server_name $name {
+    backend.example.com      backend;
+    default                  backend2;
+}
+
+upstream backend {
+    server 192.168.0.1:12345;
+    server 192.168.0.2:12345;
+}
+
+upstream backend2 {
+    server 192.168.0.3:12345;
+    server 192.168.0.4:12345;
+}
+
+server {
+    listen      12346;
+    proxy_pass  $name;
+    ssl_preread on;
+}
+</example>
+
+</para>
+
+</section>
+
+
+<section id="directives" name="Directives">
+
+<directive name="ssl_preread">
+<syntax><literal>on</literal> | <literal>off</literal></syntax>
+<default>off</default>
+<context>stream</context>
+<context>server</context>
+
+<para>
+Enables extracting information from the ClientHello message at
+the <link doc="stream_processing.xml" id="preread_phase">preread</link> phase.
+</para>
+
+</directive>
+
+</section>
+
+
+<section id="variables" name="Embedded Variables">
+
+<para>
+<list type="tag">
+
+<tag-name id="var_ssl_preread_server_name"><var>$ssl_preread_server_name</var></tag-name>
+<tag-desc>
+returns the server name requested through SNI
+</tag-desc>
+
+</list>
+</para>
+
+</section>
+
+</module>
diff --git a/xml/en/docs/stream/stream_processing.xml b/xml/en/docs/stream/stream_processing.xml
--- a/xml/en/docs/stream/stream_processing.xml
+++ b/xml/en/docs/stream/stream_processing.xml
@@ -7,7 +7,7 @@
 <article name="How nginx processes a TCP/UDP session"
          link="/en/docs/stream/stream_processing.html"
          lang="en"
-         rev="1">
+         rev="2">
 
 <section>
 
@@ -57,8 +57,11 @@ module is invoked at this phase.
 <literal>Preread</literal>
 </tag-name>
 <tag-desc>
-Reading initial bytes of data into the preread buffer
-to allow analyzing the data before its processing.
+Reading initial bytes of data into the
+<link doc="ngx_stream_core_module.xml" id="preread_buffer_size">preread buffer</link>
+to allow modules such as
+<link doc="ngx_stream_ssl_preread_module.xml">ngx_stream_ssl_preread_module</link>
+analyze the data before its processing.
 </tag-desc>
 
 <tag-name id="content_phase">
diff --git a/xml/ru/GNUmakefile b/xml/ru/GNUmakefile
--- a/xml/ru/GNUmakefile
+++ b/xml/ru/GNUmakefile
@@ -95,6 +95,7 @@ REFS =									\
 		stream/ngx_stream_return_module				\
 		stream/ngx_stream_split_clients_module			\
 		stream/ngx_stream_ssl_module				\
+		stream/ngx_stream_ssl_preread_module			\
 		stream/ngx_stream_upstream_module			\
 		stream/stream_processing				\
 
diff --git a/xml/ru/docs/index.xml b/xml/ru/docs/index.xml
--- a/xml/ru/docs/index.xml
+++ b/xml/ru/docs/index.xml
@@ -8,7 +8,7 @@
 <article name="nginx: документация"
          link="/ru/docs/"
          lang="ru"
-         rev="33"
+         rev="34"
          toc="no">
 
 
@@ -559,6 +559,11 @@ ngx_stream_ssl_module</link>
 </listitem>
 
 <listitem>
+<link doc="stream/ngx_stream_ssl_preread_module.xml">
+ngx_stream_ssl_preread_module</link>
+</listitem>
+
+<listitem>
 <link doc="stream/ngx_stream_upstream_module.xml">
 ngx_stream_upstream_module</link>
 </listitem>
diff --git a/xml/ru/docs/stream/ngx_stream_core_module.xml b/xml/ru/docs/stream/ngx_stream_core_module.xml
--- a/xml/ru/docs/stream/ngx_stream_core_module.xml
+++ b/xml/ru/docs/stream/ngx_stream_core_module.xml
@@ -9,7 +9,7 @@
 <module name="Модуль ngx_stream_core_module"
         link="/ru/docs/stream/ngx_stream_core_module.html"
         lang="ru"
-        rev="20">
+        rev="21">
 
 <section id="summary">
 
@@ -241,6 +241,36 @@ FreeBSD 9.0-STABLE)
 </directive>
 
 
+<directive name="preread_buffer_size">
+<syntax><value>размер</value></syntax>
+<default>16k</default>
+<context>stream</context>
+<context>server</context>
+<appeared-in>1.11.5</appeared-in>
+
+<para>
+Задаёт <value>размер</value> буфера
+<link doc="stream_processing.xml" id="preread_phase">предварительного чтения</link>.
+</para>
+
+</directive>
+
+
+<directive name="preread_timeout">
+<syntax><value>время</value></syntax>
+<default>30s</default>
+<context>stream</context>
+<context>server</context>
+<appeared-in>1.11.5</appeared-in>
+
+<para>
+Задаёт <value>время</value> фазы
+<link doc="stream_processing.xml" id="preread_phase">предварительного чтения</link>.
+</para>
+
+</directive>
+
+
 <directive name="proxy_protocol_timeout">
 <syntax><value>время</value></syntax>
 <default>30s</default>
diff --git a/xml/ru/docs/stream/ngx_stream_ssl_preread_module.xml b/xml/ru/docs/stream/ngx_stream_ssl_preread_module.xml
new file mode 100644
--- /dev/null
+++ b/xml/ru/docs/stream/ngx_stream_ssl_preread_module.xml
@@ -0,0 +1,94 @@
+<?xml version="1.0"?>
+
+<!--
+  Copyright (C) Nginx, Inc.
+  -->
+
+<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
+
+<module name="Модуль ngx_stream_ssl_preread_module"
+        link="/ru/docs/stream/ngx_stream_ssl_preread_module.html"
+        lang="ru"
+        rev="1">
+
+<section id="summary">
+
+<para>
+Модуль <literal>ngx_stream_ssl_preread_module</literal> (1.11.5) позволяет
+извлекать информацию из сообщения
+<link url="https://tools.ietf.org/html/rfc5246#section-7.4.1.2">ClientHello</link>
+без терминирования SSL/TLS,
+например имя сервера, запрошенное через
+<link url="https://tools.ietf.org/html/rfc6066#section-3">SNI</link>.
+По умолчанию этот модуль не собирается, его сборку необходимо
+разрешить с помощью конфигурационного параметра
+<literal>--with-stream_ssl_preread_module</literal>.
+</para>
+
+</section>
+
+
+<section id="example" name="Пример конфигурации">
+
+<para>
+<example>
+map $ssl_preread_server_name $name {
+    backend.example.com      backend;
+    default                  backend2;
+}
+
+upstream backend {
+    server 192.168.0.1:12345;
+    server 192.168.0.2:12345;
+}
+
+upstream backend2 {
+    server 192.168.0.3:12345;
+    server 192.168.0.4:12345;
+}
+
+server {
+    listen      12346;
+    proxy_pass  $name;
+    ssl_preread on;
+}
+</example>
+</para>
+
+</section>
+
+
+<section id="directives" name="Директивы">
+
+<directive name="ssl_preread">
+<syntax><literal>on</literal> | <literal>off</literal></syntax>
+<default>off</default>
+<context>stream</context>
+<context>server</context>
+
+<para>
+Разрешает извлечение информации из сообщения ClientHello во время фазы
+<link doc="stream_processing.xml" id="preread_phase">предварительного чтения</link>.
+</para>
+
+</directive>
+
+</section>
+
+
+<section id="variables" name="Встроенные переменные">
+
+<para>
+<list type="tag">
+
+<tag-name id="var_ssl_preread_server_name"><var>$ssl_preread_server_name</var></tag-name>
+<tag-desc>
+возвращает имя сервера, запрошенное через SNI
+</tag-desc>
+
+</list>
+</para>
+
+</section>
+
+</module>
diff --git a/xml/ru/docs/stream/stream_processing.xml b/xml/ru/docs/stream/stream_processing.xml
--- a/xml/ru/docs/stream/stream_processing.xml
+++ b/xml/ru/docs/stream/stream_processing.xml
@@ -7,7 +7,7 @@
 <article name="Как nginx обрабатывает TCP/UDP-сессии"
          link="/ru/docs/stream/stream_processing.html"
          lang="ru"
-         rev="1">
+         rev="2">
 
 <section>
 
@@ -58,8 +58,12 @@
 <literal>Preread</literal>
 </tag-name>
 <tag-desc>
-Чтение первых байт данных в буфер предварительного чтения
-для анализа перед их обработкой
+Чтение первых байт данных в
+<link doc="ngx_stream_core_module.xml" id="preread_buffer_size">буфер
+предварительного чтения</link> для анализа,
+например модулем
+<link doc="ngx_stream_ssl_preread_module.xml">ngx_stream_ssl_preread_module</link>,
+перед их обработкой
 </tag-desc>
 
 <tag-name id="content_phase">