diff xml/en/docs/http/ngx_http_core_module.xml @ 2903:44f3b52c0679

Documented the $proxy_protocol_tlv_ variable.
author Yaroslav Zhuravlev <yar@nginx.com>
date Wed, 19 Oct 2022 12:33:55 +0100
parents e06cf66a9f63
children 7ebe15d6c68d
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_core_module.xml	Fri Oct 21 12:20:28 2022 +0100
+++ b/xml/en/docs/http/ngx_http_core_module.xml	Wed Oct 19 12:33:55 2022 +0100
@@ -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_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>