[PATCH] Documented the http2 directive

[Yaroslav Zhuravlev]

> On 13 Jun 2023, at 15:46, Maxim Dounin <mdounin at mdounin.ru> wrote:

[...]

>> +<para>
>> +Enables
>> +the <link url="https://datatracker.ietf.org/doc/html/rfc9113">HTTP/2</link>
>> +protocol.
>> +</para>
> 
> This probably needs some more details.
> 
> In particular:
> 
> - For SNI-based virtual servers, this only fully works with 
>  OpenSSL 1.0.2h and up.  For older OpenSSL versions (1.0.2 - 1.0.2g), 
>  HTTP/2 needs to be enabled in the default virtual server as well.
> 
> - For non-SSL listening sockets, HTTP/2 needs to be enabled in
>  the default virtual server as well.
> 
> Do not insist on adding it right now though, a separate patch 
> clarifying the details should be good enough.
> 
> [...]
> 

Thank you, the patch was updated with Sergey comments, 
and I'll create a separate patch explaining these details.

# HG changeset patch
# User Yaroslav Zhuravlev <yar at nginx.com>
# Date 1686668685 -3600
#      Tue Jun 13 16:04:45 2023 +0100
# Node ID b42c78a25477b40c78c048cd3d8f44421e814fca
# Parent  2fa6471cd138071038f055031a7a379a7e9ab108
Documented the http2 directive.

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="105">
+        rev="106">
   <section id="directives" name="Directives">
  @@ -1384,6 +1384,11 @@
 Normally, for this to work the <literal>ssl</literal> parameter should be
 specified as well, but nginx can also be configured to accept HTTP/2
 connections without SSL.
+<note>
+The parameter is deprecated,
+the <link doc="ngx_http_v2_module.xml" id="http2">http2</link> directive
+should be used instead.
+</note>
 </para>
   <para id="quic">
diff --git a/xml/en/docs/http/ngx_http_grpc_module.xml b/xml/en/docs/http/ngx_http_grpc_module.xml
--- a/xml/en/docs/http/ngx_http_grpc_module.xml
+++ b/xml/en/docs/http/ngx_http_grpc_module.xml
@@ -10,7 +10,7 @@
 <module name="Module ngx_http_grpc_module"
         link="/en/docs/http/ngx_http_grpc_module.html"
         lang="en"
-        rev="9">
+        rev="10">
   <section id="summary">
  @@ -29,7 +29,9 @@
 <para>
 <example>
 server {
-    listen 9000 http2;
+    listen 9000;
+
+    http2 on;
       location / {
         grpc_pass 127.0.0.1:9000;
diff --git a/xml/en/docs/http/ngx_http_v2_module.xml b/xml/en/docs/http/ngx_http_v2_module.xml
--- a/xml/en/docs/http/ngx_http_v2_module.xml
+++ b/xml/en/docs/http/ngx_http_v2_module.xml
@@ -9,7 +9,7 @@
 <module name="Module ngx_http_v2_module"
         link="/en/docs/http/ngx_http_v2_module.html"
         lang="en"
-        rev="15">
+        rev="16">
   <section id="summary">
  @@ -55,7 +55,9 @@
 <para>
 <example>
 server {
-    listen 443 ssl http2;
+    listen 443 ssl;
+
+    http2 on;
       ssl_certificate server.crt;
     ssl_certificate_key server.key;
@@ -82,6 +84,22 @@
   <section id="directives" name="Directives">
  +<directive name="http2">
+<syntax><literal>on</literal> | <literal>off</literal></syntax>
+<default>off</default>
+<context>http</context>
+<context>server</context>
+<appeared-in>1.25.1</appeared-in>
+
+<para>
+Enables
+the <link url="https://datatracker.ietf.org/doc/html/rfc9113">HTTP/2</link>
+protocol.
+</para>
+
+</directive>
+
+
 <directive name="http2_body_preread_size">
 <syntax><value>size</value></syntax>
 <default>64k</default>
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="105">
+        rev="106">
   <section id="directives" name="Директивы">
  @@ -1376,6 +1376,10 @@
 Обычно, чтобы это работало, следует также указать параметр
 <literal>ssl</literal>, однако nginx можно также настроить и на приём
 HTTP/2-соединений без SSL.
+<note>
+Параметр устарел, вместо него следует использовать
+директиву <link doc="ngx_http_v2_module.xml" id="http2">http2</link>.
+</note>
 </para>
   <para id="quic">
diff --git a/xml/ru/docs/http/ngx_http_grpc_module.xml b/xml/ru/docs/http/ngx_http_grpc_module.xml
--- a/xml/ru/docs/http/ngx_http_grpc_module.xml
+++ b/xml/ru/docs/http/ngx_http_grpc_module.xml
@@ -10,7 +10,7 @@
 <module name="Модуль ngx_http_grpc_module"
         link="/ru/docs/http/ngx_http_grpc_module.html"
         lang="ru"
-        rev="9">
+        rev="10">
   <section id="summary">
  @@ -29,7 +29,9 @@
 <para>
 <example>
 server {
-    listen 9000 http2;
+    listen 9000;
+
+    http2 on;
       location / {
         grpc_pass 127.0.0.1:9000;
diff --git a/xml/ru/docs/http/ngx_http_v2_module.xml b/xml/ru/docs/http/ngx_http_v2_module.xml
--- a/xml/ru/docs/http/ngx_http_v2_module.xml
+++ b/xml/ru/docs/http/ngx_http_v2_module.xml
@@ -9,7 +9,7 @@
 <module name="Модуль ngx_http_v2_module"
         link="/ru/docs/http/ngx_http_v2_module.html"
         lang="ru"
-        rev="15">
+        rev="16">
   <section id="summary">
  @@ -55,7 +55,9 @@
 <para>
 <example>
 server {
-    listen 443 ssl http2;
+    listen 443 ssl;
+
+    http2 on;
       ssl_certificate server.crt;
     ssl_certificate_key server.key;
@@ -82,6 +84,22 @@
   <section id="directives" name="Директивы">
  +<directive name="http2">
+<syntax><literal>on</literal> | <literal>off</literal></syntax>
+<default>off</default>
+<context>http</context>
+<context>server</context>
+<appeared-in>1.25.1</appeared-in>
+
+<para>
+Разрешает
+протокол
+<link url="https://datatracker.ietf.org/doc/html/rfc9113">HTTP/2</link>.
+</para>
+
+</directive>
+
+
 <directive name="http2_body_preread_size">
 <syntax><value>размер</value></syntax>
 <default>64k</default>


[...]