[PATCH] Documented the $proxy_protocol_tlv_ variable

Sun Oct 23 04:28:23 UTC 2022

Hi,

> On 19 Oct 2022, at 13:01, Yaroslav Zhuravlev <yar at nginx.com> wrote:
> 
> xml/en/docs/http/ngx_http_core_module.xml     |  107 +++++++++++++++++++++++++-
> xml/en/docs/stream/ngx_stream_core_module.xml |  105 +++++++++++++++++++++++++-
> xml/ru/docs/http/ngx_http_core_module.xml     |  106 +++++++++++++++++++++++++-
> xml/ru/docs/stream/ngx_stream_core_module.xml |  106 +++++++++++++++++++++++++-
> 4 files changed, 420 insertions(+), 4 deletions(-)
> 
> 
> # HG changeset patch
> # User Yaroslav Zhuravlev <yar at nginx.com>
> # Date 1666118553 -3600
> #      Tue Oct 18 19:42:33 2022 +0100
> # Node ID 881627fb56bfff009297b6cc15cd1f5d58ebc030
> # Parent  3f5e91af4a52c5b8bbc75c0ea31e3ceac0bebea8
> Documented the $proxy_protocol_tlv_ variable.
> 
> diff --git a/xml/en/docs/http/ngx_http_core_module.xml b/xml/en/docs/http/ngx_http_core_module.xml
> --- 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 @@
> </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_0x22
> +</example>
> +
> +<para>
> +The following TLV type names are supported:
> +<list type="bullet">
> +
> +<listitem>
> +<literal>alpn</literal> (<literal>0x01</literal>)—
> +upper layer protocol used over the connection
> +</listitem>
> +
> +<listitem>
> +<literal>authority</literal> (<literal>0x02</literal>)—
> +host name value passed by the client
> +</listitem>
> +
> +<listitem>
> +<literal>unique_id</literal> (<literal>0x05</literal>)—
> +unique connection id
> +</listitem>
> +
> +<listitem>
> +<literal>netns</literal> (<literal>0x30</literal>)—
> +name of the namespace
> +</listitem>
> +
> +<listitem>
> +<literal>ssl</literal> (<literal>0x20</literal>)—
> +client SSL fields as binary
> +</listitem>
> +
> +</list>
> +</para>
> +
> +<para>
> +The following SSL TLV type names are supported:
> +<list type="bullet">
> +
> +<listitem>
> +<literal>ssl_version</literal> (<literal>0x21</literal>)—
> +SSL version used in client connection
> +</listitem>
> +
> +<listitem>
> +<literal>ssl_cn</literal> (<literal>0x22</literal>)—
> +SSL certificate Common Name
> +</listitem>
> +
> +<listitem>
> +<literal>ssl_cipher</literal> (<literal>0x23</literal>)—
> +name of the used cipher
> +</listitem>
> +
> +<listitem>
> +<literal>ssl_sig_alg</literal> (<literal>0x24</literal>)—
> +algorithm used to sign the certificate
> +</listitem>
> +
> +<listitem>
> +<literal>ssl_key_alg</literal> (<literal>0x25</literal>)—
> +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>—
> +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>
> 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="35">
> +        rev="36">
> 
> <section id="summary">
> 
> @@ -587,6 +587,109 @@
> </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_0x22
> +</example>
> +
> +<para>
> +The following TLV type names are supported:
> +<list type="bullet">
> +
> +<listitem>
> +<literal>alpn</literal> (<literal>0x01</literal>)—
> +upper layer protocol used over the connection
> +</listitem>
> +
> +<listitem>
> +<literal>authority</literal> (<literal>0x02</literal>)—
> +host name value passed by the client
> +</listitem>
> +
> +<listitem>
> +<literal>unique_id</literal> (<literal>0x05</literal>)—
> +unique connection id
> +</listitem>
> +
> +<listitem>
> +<literal>netns</literal> (<literal>0x30</literal>)—
> +name of the namespace
> +</listitem>
> +
> +<listitem>
> +<literal>ssl</literal> (<literal>0x20</literal>)—
> +client SSL fields as binary
> +</listitem>
> +
> +</list>
> +</para>
> +
> +<para>
> +The following SSL TLV type names are supported:
> +<list type="bullet">
> +
> +<listitem>
> +<literal>ssl_version</literal> (<literal>0x21</literal>)—
> +SSL version used in client connection
> +</listitem>
> +
> +<listitem>
> +<literal>ssl_cn</literal> (<literal>0x22</literal>)—
> +SSL certificate Common Name
> +</listitem>
> +
> +<listitem>
> +<literal>ssl_cipher</literal> (<literal>0x23</literal>)—
> +name of the used cipher
> +</listitem>
> +
> +<listitem>
> +<literal>ssl_sig_alg</literal> (<literal>0x24</literal>)—
> +algorithm used to sign the certificate
> +</listitem>
> +
> +<listitem>
> +<literal>ssl_key_alg</literal> (<literal>0x25</literal>)—
> +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>—
> +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
> diff --git a/xml/ru/docs/http/ngx_http_core_module.xml b/xml/ru/docs/http/ngx_http_core_module.xml
> --- 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 @@
> </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_0x22
> +</example>
> +
> +<para>
> +Поддерживаются следующие имена типов TLV:
> +<list type="bullet">
> +
> +<listitem>
> +<literal>alpn</literal> (<literal>0x01</literal>)—
> +протокол более высокого уровня, используемый поверх соединения
> +</listitem>
> +
> +<listitem>
> +<literal>authority</literal> (<literal>0x02</literal>)—
> +значение имени хоста, передаваемое клиентом
> +</listitem>
> +
> +<listitem>
> +<literal>unique_id</literal> (<literal>0x05</literal>)—
> +уникальный идентификатор соединения
> +</listitem>
> +
> +<listitem>
> +<literal>netns</literal> (<literal>0x30</literal>)—
> +имя пространства имён
> +</listitem>
> +
> +<listitem>
> +<literal>ssl</literal> (<literal>0x20</literal>)—
> +клиентские SSL поля в бинарном виде
> +</listitem>
> +
> +</list>
> +</para>
> +
> +<para>
> +Поддерживаются следующие имена типов SSL TLV:
> +<list type="bullet">
> +
> +<listitem>
> +<literal>ssl_version</literal> (<literal>0x21</literal>)—
> +версия SSL, используемая в клиентском соединении
> +</listitem>
> +
> +<listitem>
> +<literal>ssl_cn</literal> (<literal>0x22</literal>)—
> +Common Name сертификата
> +</listitem>
> +
> +<listitem>
> +<literal>ssl_cipher</literal> (<literal>0x23</literal>)—
> +имя используемого шифра
> +</listitem>
> +
> +<listitem>
> +<literal>ssl_sig_alg</literal> (<literal>0x24</literal>)—
> +алгоритм, используемый для подписи сертификата
> +</listitem>
> +
> +<listitem>
> +<literal>ssl_key_alg</literal> (<literal>0x25</literal>)—
> +алгоритм публичного ключа
> +</listitem>
> +
> +</list>
> +</para>
> +
> +<para>
> +Также поддерживается следующее специальное имя типа SSL TLV:
> +<list type="bullet">
> +
> +<listitem>
> +<literal>ssl_verify</literal>—
> +результат проверки клиентского сертификата:
> +<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>
> 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="35">
> +        rev="36">
> 
> <section id="summary">
> 
> @@ -591,6 +591,110 @@
> </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_0x22
> +</example>
> +
> +<para>
> +Поддерживаются следующие имена типов TLV:
> +<list type="bullet">
> +
> +<listitem>
> +<literal>alpn</literal> (<literal>0x01</literal>)—
> +протокол более высокого уровня, используемый поверх соединения
> +</listitem>
> +
> +<listitem>
> +<literal>authority</literal> (<literal>0x02</literal>)—
> +значение имени хоста, передаваемое клиентом
> +</listitem>
> +
> +<listitem>
> +<literal>unique_id</literal> (<literal>0x05</literal>)—
> +уникальный идентификатор соединения
> +</listitem>
> +
> +<listitem>
> +<literal>netns</literal> (<literal>0x30</literal>)—
> +имя пространства имён
> +</listitem>
> +
> +<listitem>
> +<literal>ssl</literal> (<literal>0x20</literal>)—
> +клиентские SSL поля в бинарном виде
> +</listitem>
> +
> +</list>
> +</para>
> +
> +<para>
> +Поддерживаются следующие имена типов SSL TLV:
> +<list type="bullet">
> +
> +<listitem>
> +<literal>ssl_version</literal> (<literal>0x21</literal>)—
> +версия SSL, используемая в клиентском соединении
> +</listitem>
> +
> +<listitem>
> +<literal>ssl_cn</literal> (<literal>0x22</literal>)—
> +Common Name сертификата
> +</listitem>
> +
> +<listitem>
> +<literal>ssl_cipher</literal> (<literal>0x23</literal>)—
> +имя используемого шифра
> +</listitem>
> +
> +<listitem>
> +<literal>ssl_sig_alg</literal> (<literal>0x24</literal>)—
> +алгоритм, используемый для подписи сертификата
> +</listitem>
> +
> +<listitem>
> +<literal>ssl_key_alg</literal> (<literal>0x25</literal>)—
> +алгоритм публичного ключа
> +</listitem>
> +
> +</list>
> +</para>
> +
> +<para>
> +Также поддерживается следующее специальное имя типа SSL TLV:
> +<list type="bullet">
> +
> +<listitem>
> +<literal>ssl_verify</literal>—
> +результат проверки клиентского сертификата:
> +<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>
> адрес клиента
> _______________________________________________
> nginx-devel mailing list -- nginx-devel at nginx.org
> To unsubscribe send an email to nginx-devel-leave at nginx.org

This has been slightly updated during internal review,

Overall, looks good to me.

----
Roman Arutyunyan
arut at nginx.com

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailman.nginx.org/pipermail/nginx-devel/attachments/20221023/0d105e0e/attachment.htm>