Mercurial > hg > nginx-site
changeset 1798:59d1f512c3a0
Documented the ngx_stream_ssl_preread_module module.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Wed, 21 Sep 2016 20:46:16 +0300 |
parents | be868c8f6e9c |
children | 386a9a8a7ddc |
files | xml/en/GNUmakefile xml/en/docs/index.xml xml/en/docs/stream/ngx_stream_core_module.xml xml/en/docs/stream/ngx_stream_ssl_preread_module.xml xml/en/docs/stream/stream_processing.xml xml/ru/GNUmakefile xml/ru/docs/index.xml xml/ru/docs/stream/ngx_stream_core_module.xml xml/ru/docs/stream/ngx_stream_ssl_preread_module.xml xml/ru/docs/stream/stream_processing.xml |
diffstat | 10 files changed, 278 insertions(+), 10 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/GNUmakefile Wed Sep 21 15:35:35 2016 +0300 +++ b/xml/en/GNUmakefile Wed Sep 21 20:46:16 2016 +0300 @@ -107,6 +107,7 @@ 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 \
--- a/xml/en/docs/index.xml Wed Sep 21 15:35:35 2016 +0300 +++ b/xml/en/docs/index.xml Wed Sep 21 20:46:16 2016 +0300 @@ -8,7 +8,7 @@ <article name="nginx documentation" link="/en/docs/" lang="en" - rev="33" + rev="34" toc="no"> @@ -555,6 +555,11 @@ </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>
--- a/xml/en/docs/stream/ngx_stream_core_module.xml Wed Sep 21 15:35:35 2016 +0300 +++ b/xml/en/docs/stream/ngx_stream_core_module.xml Wed Sep 21 20:46:16 2016 +0300 @@ -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 @@ </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>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/en/docs/stream/ngx_stream_ssl_preread_module.xml Wed Sep 21 20:46:16 2016 +0300 @@ -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>
--- a/xml/en/docs/stream/stream_processing.xml Wed Sep 21 15:35:35 2016 +0300 +++ b/xml/en/docs/stream/stream_processing.xml Wed Sep 21 20:46:16 2016 +0300 @@ -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 @@ <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">
--- a/xml/ru/GNUmakefile Wed Sep 21 15:35:35 2016 +0300 +++ b/xml/ru/GNUmakefile Wed Sep 21 20:46:16 2016 +0300 @@ -95,6 +95,7 @@ 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 \
--- a/xml/ru/docs/index.xml Wed Sep 21 15:35:35 2016 +0300 +++ b/xml/ru/docs/index.xml Wed Sep 21 20:46:16 2016 +0300 @@ -8,7 +8,7 @@ <article name="nginx: документация" link="/ru/docs/" lang="ru" - rev="33" + rev="34" toc="no"> @@ -559,6 +559,11 @@ </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>
--- a/xml/ru/docs/stream/ngx_stream_core_module.xml Wed Sep 21 15:35:35 2016 +0300 +++ b/xml/ru/docs/stream/ngx_stream_core_module.xml Wed Sep 21 20:46:16 2016 +0300 @@ -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 @@ </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>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/stream/ngx_stream_ssl_preread_module.xml Wed Sep 21 20:46:16 2016 +0300 @@ -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>
--- a/xml/ru/docs/stream/stream_processing.xml Wed Sep 21 15:35:35 2016 +0300 +++ b/xml/ru/docs/stream/stream_processing.xml Wed Sep 21 20:46:16 2016 +0300 @@ -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">