Mercurial > hg > nginx-site

changeset 2903:44f3b52c0679

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented the $proxy_protocol_tlv_ variable.
author Yaroslav Zhuravlev <yar@nginx.com>
date Wed, 19 Oct 2022 12:33:55 +0100
parents 843bf979dcaa
children 4aaab86a9c26
files xml/en/docs/http/ngx_http_core_module.xml xml/en/docs/stream/ngx_stream_core_module.xml xml/ru/docs/http/ngx_http_core_module.xml xml/ru/docs/stream/ngx_stream_core_module.xml
diffstat 4 files changed, 420 insertions(+), 4 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_core_module.xml
+++ b/xml/en/docs/http/ngx_http_core_module.xml
@@ -10,7 +10,7 @@
 <module name="Module ngx_http_core_module"
         link="/en/docs/http/ngx_http_core_module.html"
         lang="en"
-        rev="100">
+        rev="101">
 
 <section id="directives" name="Directives">
 
@@ -3228,6 +3228,111 @@ in the <link id="listen"/> directive.
 </para>
 </tag-desc>
 
+<tag-name id="var_proxy_protocol_tlv_"><var>$proxy_protocol_tlv_</var><value>name</value></tag-name>
+<tag-desc>
+TLV from the PROXY Protocol header (1.23.2).
+The <literal>name</literal> can be a TLV type name or its numeric value.
+In the latter case, the value is hexadecimal
+and should be prefixed with <literal>0x</literal>:
+
+<example>
+$proxy_protocol_tlv_alpn
+$proxy_protocol_tlv_0x01
+</example>
+SSL TLVs can also be accessed by TLV type name
+or its numeric value,
+both prefixed by <literal>ssl_</literal>:
+<example>
+$proxy_protocol_tlv_ssl_version
+$proxy_protocol_tlv_ssl_0x21
+</example>
+
+<para>
+The following TLV type names are supported:
+<list type="bullet">
+
+<listitem>
+<literal>alpn</literal> (<literal>0x01</literal>)&mdash;
+upper layer protocol used over the connection
+</listitem>
+
+<listitem>
+<literal>authority</literal> (<literal>0x02</literal>)&mdash;
+host name value passed by the client
+</listitem>
+
+<listitem>
+<literal>unique_id</literal> (<literal>0x05</literal>)&mdash;
+unique connection id
+</listitem>
+
+<listitem>
+<literal>netns</literal> (<literal>0x30</literal>)&mdash;
+name of the namespace
+</listitem>
+
+<listitem>
+<literal>ssl</literal> (<literal>0x20</literal>)&mdash;
+binary SSL TLV structure
+</listitem>
+
+</list>
+</para>
+
+<para>
+The following SSL TLV type names are supported:
+<list type="bullet">
+
+<listitem>
+<literal>ssl_version</literal> (<literal>0x21</literal>)&mdash;
+SSL version used in client connection
+</listitem>
+
+<listitem>
+<literal>ssl_cn</literal> (<literal>0x22</literal>)&mdash;
+SSL certificate Common Name
+</listitem>
+
+<listitem>
+<literal>ssl_cipher</literal> (<literal>0x23</literal>)&mdash;
+name of the used cipher
+</listitem>
+
+<listitem>
+<literal>ssl_sig_alg</literal> (<literal>0x24</literal>)&mdash;
+algorithm used to sign the certificate
+</listitem>
+
+<listitem>
+<literal>ssl_key_alg</literal> (<literal>0x25</literal>)&mdash;
+public-key algorithm
+</listitem>
+
+</list>
+</para>
+
+<para>
+Also, the following special SSL TLV type name is supported:
+<list type="bullet">
+
+<listitem>
+<literal>ssl_verify</literal>&mdash;
+client SSL certificate verification result,
+<literal>0</literal> if the client presented a certificate
+and it was successfully verified,
+non-zero otherwise.
+</listitem>
+
+</list>
+</para>
+
+<para>
+The PROXY protocol must be previously enabled by setting the
+<literal>proxy_protocol</literal> parameter
+in the <link id="listen"/> directive.
+</para>
+</tag-desc>
+
 <tag-name id="var_query_string"><var>$query_string</var></tag-name>
 <tag-desc>
 same as <var>$args</var>
--- 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="35">
+        rev="36">
 
 <section id="summary">
 
@@ -587,6 +587,109 @@ in the <link id="listen"/> directive.
 </para>
 </tag-desc>
 
+<tag-name id="var_proxy_protocol_tlv_"><var>$proxy_protocol_tlv_</var><value>name</value></tag-name>
+<tag-desc>
+TLV from the PROXY Protocol header (1.23.2).
+The <literal>name</literal> can be a TLV type name or its numeric value.
+In the latter case, the value is hexadecimal
+and should be prefixed with <literal>0x</literal>:
+
+<example>
+$proxy_protocol_tlv_alpn
+$proxy_protocol_tlv_0x01
+</example>
+SSL TLVs can also be accessed by TLV type name or its numeric value,
+both prefixed by <literal>ssl_</literal>:
+<example>
+$proxy_protocol_tlv_ssl_version
+$proxy_protocol_tlv_ssl_0x21
+</example>
+
+<para>
+The following TLV type names are supported:
+<list type="bullet">
+
+<listitem>
+<literal>alpn</literal> (<literal>0x01</literal>)&mdash;
+upper layer protocol used over the connection
+</listitem>
+
+<listitem>
+<literal>authority</literal> (<literal>0x02</literal>)&mdash;
+host name value passed by the client
+</listitem>
+
+<listitem>
+<literal>unique_id</literal> (<literal>0x05</literal>)&mdash;
+unique connection id
+</listitem>
+
+<listitem>
+<literal>netns</literal> (<literal>0x30</literal>)&mdash;
+name of the namespace
+</listitem>
+
+<listitem>
+<literal>ssl</literal> (<literal>0x20</literal>)&mdash;
+binary SSL TLV structure
+</listitem>
+
+</list>
+</para>
+
+<para>
+The following SSL TLV type names are supported:
+<list type="bullet">
+
+<listitem>
+<literal>ssl_version</literal> (<literal>0x21</literal>)&mdash;
+SSL version used in client connection
+</listitem>
+
+<listitem>
+<literal>ssl_cn</literal> (<literal>0x22</literal>)&mdash;
+SSL certificate Common Name
+</listitem>
+
+<listitem>
+<literal>ssl_cipher</literal> (<literal>0x23</literal>)&mdash;
+name of the used cipher
+</listitem>
+
+<listitem>
+<literal>ssl_sig_alg</literal> (<literal>0x24</literal>)&mdash;
+algorithm used to sign the certificate
+</listitem>
+
+<listitem>
+<literal>ssl_key_alg</literal> (<literal>0x25</literal>)&mdash;
+public-key algorithm
+</listitem>
+
+</list>
+</para>
+
+<para>
+Also, the following special SSL TLV type name is supported:
+<list type="bullet">
+
+<listitem>
+<literal>ssl_verify</literal>&mdash;
+client SSL certificate verification result,
+zero if the client presented a certificate
+and it was successfully verified, and non-zero otherwise
+</listitem>
+
+</list>
+</para>
+
+<para>
+The PROXY protocol must be previously enabled by setting the
+<literal>proxy_protocol</literal> parameter
+in the <link id="listen"/> directive.
+</para>
+</tag-desc>
+
 <tag-name id="var_remote_addr"><var>$remote_addr</var></tag-name>
 <tag-desc>
 client address
--- a/xml/ru/docs/http/ngx_http_core_module.xml
+++ b/xml/ru/docs/http/ngx_http_core_module.xml
@@ -10,7 +10,7 @@
 <module name="Модуль ngx_http_core_module"
         link="/ru/docs/http/ngx_http_core_module.html"
         lang="ru"
-        rev="100">
+        rev="101">
 
 <section id="directives" name="Директивы">
 
@@ -3221,6 +3221,110 @@ cookie <value>имя</value>
 </para>
 </tag-desc>
 
+<tag-name id="var_proxy_protocol_tlv_"><var>$proxy_protocol_tlv_</var><value>имя</value></tag-name>
+<tag-desc>
+TLV, полученный из заголовка протокола PROXY (1.23.2).
+<literal>Имя</literal> может быть именем типа TLV или его числовым значением.
+В последнем случае значение задаётся в шестнадцатеричном виде
+и должно начинаться с <literal>0x</literal>:
+
+<example>
+$proxy_protocol_tlv_alpn
+$proxy_protocol_tlv_0x01
+</example>
+SSL TLV могут также быть доступны как по имени типа TLV,
+так и по его числовому значению,
+оба должны начинаться с <literal>ssl_</literal>:
+<example>
+$proxy_protocol_tlv_ssl_version
+$proxy_protocol_tlv_ssl_0x21
+</example>
+
+<para>
+Поддерживаются следующие имена типов TLV:
+<list type="bullet">
+
+<listitem>
+<literal>alpn</literal> (<literal>0x01</literal>)&mdash;
+протокол более высокого уровня, используемый поверх соединения
+</listitem>
+
+<listitem>
+<literal>authority</literal> (<literal>0x02</literal>)&mdash;
+значение имени хоста, передаваемое клиентом
+</listitem>
+
+<listitem>
+<literal>unique_id</literal> (<literal>0x05</literal>)&mdash;
+уникальный идентификатор соединения
+</listitem>
+
+<listitem>
+<literal>netns</literal> (<literal>0x30</literal>)&mdash;
+имя пространства имён
+</listitem>
+
+<listitem>
+<literal>ssl</literal> (<literal>0x20</literal>)&mdash;
+структура SSL TLV в бинарном виде
+</listitem>
+
+</list>
+</para>
+
+<para>
+Поддерживаются следующие имена типов SSL TLV:
+<list type="bullet">
+
+<listitem>
+<literal>ssl_version</literal> (<literal>0x21</literal>)&mdash;
+версия SSL, используемая в клиентском соединении
+</listitem>
+
+<listitem>
+<literal>ssl_cn</literal> (<literal>0x22</literal>)&mdash;
+Common Name сертификата
+</listitem>
+
+<listitem>
+<literal>ssl_cipher</literal> (<literal>0x23</literal>)&mdash;
+имя используемого шифра
+</listitem>
+
+<listitem>
+<literal>ssl_sig_alg</literal> (<literal>0x24</literal>)&mdash;
+алгоритм, используемый для подписи сертификата
+</listitem>
+
+<listitem>
+<literal>ssl_key_alg</literal> (<literal>0x25</literal>)&mdash;
+алгоритм публичного ключа
+</listitem>
+
+</list>
+</para>
+
+<para>
+Также поддерживается следующее специальное имя типа SSL TLV:
+<list type="bullet">
+
+<listitem>
+<literal>ssl_verify</literal>&mdash;
+результат проверки клиентского сертификата:
+<literal>0</literal>, если клиент предоставил сертификат
+и он был успешно верифицирован,
+либо ненулевое значение
+</listitem>
+
+</list>
+</para>
+
+<para>
+Протокол PROXY должен быть предварительно включён при помощи установки
+параметра <literal>proxy_protocol</literal> в директиве <link id="listen"/>.
+</para>
+</tag-desc>
+
 <tag-name id="var_query_string"><var>$query_string</var></tag-name>
 <tag-desc>
 то же, что и <var>$args</var>
--- 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="35">
+        rev="36">
 
 <section id="summary">
 
@@ -591,6 +591,110 @@ resolver_timeout 5s;
 </para>
 </tag-desc>
 
+<tag-name id="var_proxy_protocol_tlv_"><var>$proxy_protocol_tlv_</var><value>имя</value></tag-name>
+<tag-desc>
+TLV, полученный из заголовка протокола PROXY (1.23.2).
+<literal>Имя</literal> может быть именем типа TLV или его числовым значением.
+В последнем случае значение задаётся в шестнадцатеричном виде
+и должно начинаться с <literal>0x</literal>:
+
+<example>
+$proxy_protocol_tlv_alpn
+$proxy_protocol_tlv_0x01
+</example>
+SSL TLV могут также быть доступны как по имени типа TLV,
+так и по его числовому значению,
+оба должны начинаться с <literal>ssl_</literal>:
+<example>
+$proxy_protocol_tlv_ssl_version
+$proxy_protocol_tlv_ssl_0x21
+</example>
+
+<para>
+Поддерживаются следующие имена типов TLV:
+<list type="bullet">
+
+<listitem>
+<literal>alpn</literal> (<literal>0x01</literal>)&mdash;
+протокол более высокого уровня, используемый поверх соединения
+</listitem>
+
+<listitem>
+<literal>authority</literal> (<literal>0x02</literal>)&mdash;
+значение имени хоста, передаваемое клиентом
+</listitem>
+
+<listitem>
+<literal>unique_id</literal> (<literal>0x05</literal>)&mdash;
+уникальный идентификатор соединения
+</listitem>
+
+<listitem>
+<literal>netns</literal> (<literal>0x30</literal>)&mdash;
+имя пространства имён
+</listitem>
+
+<listitem>
+<literal>ssl</literal> (<literal>0x20</literal>)&mdash;
+структура SSL TLV в бинарном виде
+</listitem>
+
+</list>
+</para>
+
+<para>
+Поддерживаются следующие имена типов SSL TLV:
+<list type="bullet">
+
+<listitem>
+<literal>ssl_version</literal> (<literal>0x21</literal>)&mdash;
+версия SSL, используемая в клиентском соединении
+</listitem>
+
+<listitem>
+<literal>ssl_cn</literal> (<literal>0x22</literal>)&mdash;
+Common Name сертификата
+</listitem>
+
+<listitem>
+<literal>ssl_cipher</literal> (<literal>0x23</literal>)&mdash;
+имя используемого шифра
+</listitem>
+
+<listitem>
+<literal>ssl_sig_alg</literal> (<literal>0x24</literal>)&mdash;
+алгоритм, используемый для подписи сертификата
+</listitem>
+
+<listitem>
+<literal>ssl_key_alg</literal> (<literal>0x25</literal>)&mdash;
+алгоритм публичного ключа
+</listitem>
+
+</list>
+</para>
+
+<para>
+Также поддерживается следующее специальное имя типа SSL TLV:
+<list type="bullet">
+
+<listitem>
+<literal>ssl_verify</literal>&mdash;
+результат проверки клиентского сертификата:
+<literal>0</literal>, если клиент предоставил сертификат
+и он был успешно верифицирован,
+либо ненулевое значение
+</listitem>
+
+</list>
+</para>
+
+<para>
+Протокол PROXY должен быть предварительно включён при помощи установки
+параметра <literal>proxy_protocol</literal> в директиве <link id="listen"/>.
+</para>
+</tag-desc>
+
 <tag-name id="var_remote_addr"><var>$remote_addr</var></tag-name>
 <tag-desc>
 адрес клиента