Модуль Apache mod_http2

Директива H2CopyFiles

H2CopyFiles on|off

H2CopyFiles off

Эта директива влияет на обработку содержимого файлов в ответах. Если задано off, что является значением по умолчанию, дескрипторы файлов передаются от обработчика запросов основному соединению с использованием стандартного механизма Apache setaside для управления временем жизни файла.

Если задано on, содержимое файла копируется, пока запрос еще обрабатывается, а буферизованные данные передаются основному соединению. Это предпочтительный вариант, если сторонний модуль добавляет в ответ файлы с другим временем жизни.

Примером такого модуля является mod_wsgi, который может помещать в ответ дескрипторы файлов Python. Эти файлы закрываются, когда Python считает обработку завершенной. Это может произойти задолго до того, как mod_http2 закончит с ними работу.

Директива H2Direct

H2Direct on|off

H2Direct on for h2c, off for h2 protocol

Эта директива включает или отключает прямой режим HTTP/2. Для включения прямого взаимодействия по HTTP/2 в соответствующем виртуальном хосте ее следует использовать внутри секции <VirtualHost>.

Прямое взаимодействие означает, что если первые байты, полученные сервером через соединение, соответствуют преамбуле HTTP/2, происходит немедленное переключение на протокол HTTP/2 без дополнительного согласования. Этот режим определен в RFC 7540 для случая открытого текста (h2c). Стандарт не требует его использования в соединениях TLS.

Если для сервера или виртуального хоста не включены h2 или h2c с помощью Protocols, соединение не проверяется на наличие преамбулы HTTP/2. В этом случае H2Direct не имеет значения. Это важно для соединений, использующих протоколы, при работе с которыми первоначальное чтение может зависнуть на неопределенное время, например NNTP.

Для клиентов, которым из другого источника известно, что сервер поддерживает h2c, прямой режим HTTP/2 избавляет от необходимости выполнять обновление HTTP/1.1, что повышает производительность и снимает ограничения обновления, касающиеся тел запросов.

Поэтому прямой режим h2c подходит и для взаимодействия между серверами, если соединению можно доверять или оно защищено иными средствами.

H2Direct on

Директива H2EarlyHint

H2EarlyHint name value

H2EarlyHint позволяет добавить заголовок ответа до начала фактической обработки запроса. Такие заголовки включаются в промежуточные ответы «103 Early Hints». Главная цель — передать браузерам клиентов сведения «preload».

name и value должны быть допустимыми полями заголовка HTTP, иначе обработка ответа завершится ошибкой. Для отправки промежуточных ответов 103 по-прежнему необходимо включить H2EarlyHints. Эту директиву можно указывать несколько раз; поля заголовка с одинаковыми именами добавляются друг к другу.

H2EarlyHint Link "</my.css>;rel=preload;as=style"

Директива H2EarlyHints

H2EarlyHints on|off

H2EarlyHints off

Эта настройка определяет, будут ли промежуточные ответы с кодом состояния HTTP 103 передаваться клиенту. В настоящее время по умолчанию они не передаются, поскольку многие клиенты по-прежнему испытывают проблемы с неожиданными промежуточными ответами.

Если задано on, ресурсы PUSH, объявленные с помощью H2PushResource, вызовут отправку промежуточного ответа 103 перед окончательным ответом. Ответ 103 будет содержать заголовки Link, уведомляющие preload об этих ресурсах.

Директива H2MaxDataFrameLen

H2MaxDataFrameLen n

H2MaxDataFrameLen 0

H2MaxDataFrameLen ограничивает максимальное количество байтов тела ответа, помещаемых в один кадр DATA HTTP/2. Значение 0 снимает ограничение (при этом соблюдается максимальный размер, разрешенный протоколом).

По умолчанию модуль старается использовать максимально возможный размер, примерно равный 16 КБ. Эта директива задает верхний предел. Если данных ответа доступно меньше, будут отправлены кадры меньшего размера.

Директива H2MaxHeaderBlockLen

H2MaxHeaderBlockLen n

H2MaxHeaderBlockLen 0

H2MaxHeaderBlockLen задает ограничение на общий размер заголовков ответа. Если указать 0, будет использоваться значение по умолчанию в nghttp2 — 64 КБ.

Ответы, заголовки которых (суммарно) превышают это значение, не будут обработаны, а поток будет сброшен.

Директива H2MaxSessionStreams

H2MaxSessionStreams n

H2MaxSessionStreams 100

Эта директива задает максимальное количество активных потоков на сеанс HTTP/2 (например, на соединение), разрешенное сервером. Согласно RFC 7540 поток считается активным, если он не находится в состоянии idle или closed.

H2MaxSessionStreams 20

Директива H2MaxWorkerIdleSeconds

H2MaxWorkerIdleSeconds n

H2MaxWorkerIdleSeconds 600

Эта директива задает максимальное количество секунд, в течение которых рабочий поток h2 может простаивать, прежде чем завершит работу. Это происходит только в том случае, если количество рабочих потоков h2 превышает H2MinWorkers.

H2MaxWorkerIdleSeconds 20

Директива H2MaxWorkers

H2MaxWorkers n

Эта директива задает максимальное количество рабочих потоков, создаваемых для обработки HTTP/2 в каждом дочернем процессе. Если директива не используется, mod_http2 выберет значение, подходящее для загруженного модуля mpm.

H2MaxWorkers 20

Директива H2MinWorkers

H2MinWorkers n

Эта директива задает минимальное количество рабочих потоков, создаваемых для обработки HTTP/2 в каждом дочернем процессе. Если директива не используется, mod_http2 выберет значение, подходящее для загруженного модуля mpm.

H2MinWorkers 10

Директива H2ModernTLSOnly

H2ModernTLSOnly on|off

H2ModernTLSOnly on

Эта директива включает или отключает проверки безопасности для соединений HTTP/2 в режиме TLS (https:). Ее можно использовать для всего сервера или для отдельных <VirtualHost>.

Проверки безопасности требуют, чтобы использовался протокол TLS версии не ниже TLSv1.2 и ни один из шифров, перечисленных в приложении A к RFC 7540. Эти проверки будут расширяться по мере появления новых требований безопасности.

Название происходит от определений Security/Server Side TLS проекта Mozilla, где определена «современная совместимость». Mozilla Firefox и другие браузеры требуют современной совместимости для соединений HTTP/2. Как и все в области OpSec, это постоянно меняется, и в будущем требования могут измениться.

Одна из целей включения этих проверок в mod_http2 — обеспечить этот уровень безопасности для всех соединений, а не только для соединений браузеров. Другая цель — не допустить согласования HTTP/2 в качестве протокола, если требования не выполнены.

В конечном итоге безопасность соединения TLS определяется директивами конфигурации сервера для mod_ssl.

H2ModernTLSOnly off

Директива H2OutputBuffering

H2OutputBuffering on|off

H2OutputBuffering on

Директива H2OutputBuffering управляет буферизацией вывода потока. По умолчанию она включена, как и в предыдущих версиях. Если ее отключить, все байты сразу становятся доступны основному соединению для отправки клиенту. Это устраняет проблемы взаимодействия с некоторыми вариантами gRPC.

Директива H2Padding

H2Padding numbits

H2Padding 0

При значении по умолчанию 0 байты заполнения не добавляются ни к каким кадрам с полезной нагрузкой, например HEADERS, DATA и PUSH_PROMISE. Так было и в предыдущих версиях. Это означает, что в определенных условиях наблюдатель сетевого трафика может определить длину этих кадров в потоке TLS.

Если задать значение numbits от 1 до 8, к каждому кадру добавляется случайное количество байтов из диапазона [0, 2^numbits[. Случайное значение выбирается независимо для каждого кадра, отправляемого модулем клиенту.

Чем больше байтов заполнения, тем лучше скрывается длина сообщений, однако это также увеличивает объем трафика. Поэтому оптимальное значение зависит от типа веб-трафика, обрабатываемого сервером.

Значение по умолчанию 0, то есть отсутствие заполнения, выбрано для максимальной обратной совместимости. В некоторых развертываниях байты заполнения могут быть нежелательны или вредны. Вероятнее всего, это может быть связано с ошибками в реализации клиента.

Директива H2ProxyRequests

H2ProxyRequests on|off

H2ProxyRequests off

Используйте H2ProxyRequests, чтобы включить или отключить обработку запросов HTTP/2 в конфигурации прямого прокси-сервера.

Как и ProxyRequests, эта директива обеспечивает необходимую обработку запросов при включенном HTTP/2 в конфигурации прямого прокси-сервера. Необходимо включить обе директивы.

Директива H2Push

H2Push on|off

H2Push on

Эта директива включает или отключает функцию отправки данных сервером в протоколе HTTP/2.

Протокол HTTP/2 позволяет серверу отправлять клиенту другие ресурсы в ответ на запрос одного из них. Это полезно, если ресурсы связаны между собой и можно ожидать, что клиент все равно запросит их. Отправка ресурсов сервером экономит время, которое клиенту потребовалось бы на самостоятельный запрос этих ресурсов. С другой стороны, отправка ресурсов, которые клиенту не нужны или уже имеются у него, приводит к напрасному расходу пропускной способности.

Отправка данных сервером обнаруживается путем проверки заголовков Link ответов (спецификация приведена по адресу https://tools.ietf.org/html/rfc5988). Если в указанной таким образом ссылке присутствует атрибут rel=preload, она рассматривается как ресурс для отправки.

Заголовки Link в ответах задаются приложением или могут быть настроены с помощью H2PushResource либо с помощью mod_headers следующим образом:

<Location /index.html>
    Header add Link "</css/site.css>;rel=preload"
    Header add Link "</images/logo.jpg>;rel=preload"
</Location>

Как видно из примера, в ответ можно добавить несколько заголовков Link, что приведет к отправке нескольких ресурсов. Модуль не проверяет, чтобы один и тот же ресурс не отправлялся одному клиенту дважды или более раз. Используйте эту возможность с осторожностью.

Отправка данных сервером HTTP/2 включена по умолчанию. На уровне сервера или виртуального хоста эту функцию можно включить или отключить для всех соединений с хостом. Кроме того, PUSH можно отключить для набора ресурсов в разделе Directory/Location. Это определяет, какие ресурсы могут вызвать PUSH, а не то, какие ресурсы могут быть отправлены с помощью PUSH.

H2Push off

И наконец, отправка происходит только в том случае, если клиент сообщает о готовности принять эти ресурсы. Большинство браузеров это делают, но некоторые, например Safari 9, — нет. Кроме того, отправляться могут только ресурсы с тем же authority, что и исходный ответ.

Директива H2PushDiarySize

H2PushDiarySize n

H2PushDiarySize 256

Эта директива задает максимальное количество отправок данных сервером HTTP/2, сохраняемых для каждого соединения HTTP/2. Ее можно использовать в секции <VirtualHost>, чтобы задать это значение для всех соединений с данным виртуальным хостом.

В журнале отправок хранится дайджест отправленных ресурсов (их URL), чтобы избежать повторной отправки одного ресурса в рамках одного соединения. Эти значения не сохраняются, поэтому при открытии нового соединения клиенты снова получат уже отправленные ресурсы.

При достижении максимального размера новые записи заменяют самые старые. Одна запись журнала занимает 8 байт, поэтому журнал по умолчанию из 256 записей использует около 2 КБ памяти.

Размер 0 фактически отключает журнал отправок.

Директива H2PushPriority

H2PushPriority mime-type [after|before|interleaved] [weight]

H2PushPriority * After 16

Эта директива задает приоритет обработки отправленных ответов на основе типа содержимого ответа. Обычно она задается в конфигурации сервера, но также может находиться в виртуальном хосте.

Отправка данных сервером HTTP/2 всегда связана с запросом клиента. Каждая такая пара запрос/ответ, или поток, имеет зависимость и вес, которые вместе определяют приоритет потока.

Если один поток зависит от другого, например X зависит от Y, то Y получает всю пропускную способность, прежде чем ее получит X. Обратите внимание: это не означает, что Y будет блокировать X. Если у Y нет данных для отправки, всю выделенную ему пропускную способность может использовать X.

Если от одного потока зависят несколько потоков, например X1 и X2 зависят от Y, распределение пропускной способности определяется весом. Если у X1 и X2 одинаковый вес, каждому достается половина доступной пропускной способности. Если вес X1 вдвое больше веса X2, X1 получает вдвое больше пропускной способности, чем X2.

В конечном счете каждый поток зависит от потока root, которому доступна вся пропускная способность, но который ничего не отправляет. Поэтому вся его пропускная способность распределяется по весу между дочерними потоками. Они либо отправляют данные, либо распределяют пропускную способность между собственными дочерними потоками. И так далее. Если ни у одного из дочерних потоков нет данных для отправки, эта пропускная способность распределяется в другом месте по тем же правилам.

Цель этой системы приоритетов — всегда использовать доступную пропускную способность, при этом предоставляя отдельным потокам преимущество и назначая им вес. Поскольку обычно все потоки инициируются клиентом, именно он задает их приоритеты.

Только если такой поток приводит к PUSH, серверу приходится определять начальный приоритет отправленного потока. В приведенных ниже примерах X — поток клиента. Он зависит от Y, а сервер решает отправить потоки P1 и P2 в поток X.

Правило приоритета по умолчанию:

H2PushPriority * After 16

Оно читается так: «Отправлять поток любого типа содержимого, отправленный сервером, с зависимостью от потока клиента и весом 16». Таким образом, P1 и P2 будут отправлены после X и, поскольку их веса равны, будут поровну делить пропускную способность между собой.

H2PushPriority text/css Interleaved 256

Оно читается так: «Отправлять любой ресурс CSS с теми же зависимостью и весом, что и у потока клиента». Если тип содержимого P1 — 'text/css', он будет зависеть от Y (как и X), а его эффективный вес будет вычислен по формуле P1ew = Xw * (P1w / 256). Если P1w равен 256, эффективный вес будет равен весу X. Если у X и P1 есть данные для отправки, пропускная способность будет распределена между ними поровну.

Если задать для Pw значение 512, чередующийся отправленный поток получит вдвое больший вес, чем X. При значении 128 — вдвое меньший. Обратите внимание, что эффективный вес всегда ограничен значением 256.

H2PushPriority application/json Before

Оно означает, что любой отправленный поток с типом содержимого 'application/json' должен быть отправлен до X. В этом случае P1 будет зависеть от Y, а X — от P1. Поэтому X будет приостановлен, пока у P1 есть данные для отправки. Эффективный вес наследуется от потока клиента. Указывать вес нельзя.

Помните, что действие настроек приоритета ограничено доступными ресурсами сервера. Если на сервере нет свободных рабочих потоков для отправленных потоков, данные могут поступить только после завершения обработки других потоков.

И наконец, синтаксис этой директивы имеет несколько особенностей:

1. '*' — единственный специальный тип содержимого, соответствующий всем остальным. 'image/*' работать не будет.
2. Зависимость по умолчанию — 'After'.
3. Также заданы веса по умолчанию: для 'After' это 16, для 'interleaved' — 256.

H2PushPriority application/json 32         # an After rule
H2PushPriority image/jpeg before           # weight inherited
H2PushPriority text/css   interleaved      # weight 256 default

Директива H2PushResource

H2PushResource [add] path [critical]

При добавлении к каталогу или location для всех путей, добавленных с помощью этой директивы, будут выполняться попытки HTTP/2 PUSH. Эту директиву можно использовать несколько раз для одного и того же location.

Эта директива отправляет ресурсы гораздо раньше, чем добавление заголовков Link через mod_headers. mod_http2 объявляет эти ресурсы клиенту во временном ответе 103 Early Hints. Это означает, что даже клиенты, не поддерживающие PUSH, получат ранние подсказки о предварительной загрузке.

В отличие от установки заголовков ответа Link через mod_headers, эта директива действует только для соединений HTTP/2.

Добавив critical к такому ресурсу, сервер повысит приоритет его обработки и отправит его данные сразу после их появления, до отправки данных основного запроса.

Директива H2SerializeHeaders

H2SerializeHeaders on|off

H2SerializeHeaders off

Эта директива переключает режим обработки запросов HTTP/2: они могут сериализоваться в формате HTTP/1.1 для обработки ядром httpd либо полученные двоичные данные могут напрямую передаваться в request_rec.

Сериализация снижает производительность, но обеспечивает лучшую обратную совместимость на случай, если она необходима пользовательским фильтрам или хукам.

H2SerializeHeaders on

Директива H2StreamMaxMemSize

H2StreamMaxMemSize bytes

H2StreamMaxMemSize 65536

Эта директива задает максимальное количество байтов исходящих данных, буферизуемых в памяти для активных потоков. Эта память не выделяется отдельно для каждого потока. Выделения учитываются в рамках этого ограничения непосредственно перед их выполнением. Обработка потоков приостанавливается после достижения ограничения и возобновляется, только когда буферизованные данные отправлены клиенту.

H2StreamMaxMemSize 128000

Директива H2StreamTimeout

H2StreamTimeout time-interval[s]

Value of Timeout

H2StreamTimeout задает максимальное время ожидания отправки или получения данных для обрабатываемого потока.

Директива H2TLSCoolDownSecs

H2TLSCoolDownSecs seconds

H2TLSCoolDownSecs 1

Эта директива задает количество секунд простоя TLS-соединения, по истечении которых размер записи TLS уменьшается до небольшого значения (около 1300 байт). Ее можно использовать для всего сервера или для отдельных <VirtualHost>.

Описание разогрева TLS см. в H2TLSWarmUpSize. H2TLSCoolDownSecs учитывает тот факт, что со временем качество соединений может ухудшаться (а управление потоком TCP адаптируется), в том числе и у простаивающих соединений. Для повышения общей производительности полезно возвращаться к этапу до разогрева, если данные не отправлялись в течение некоторого времени.

В средах, где соединения можно считать надежными, этот таймер можно отключить, задав ему значение 0.

В следующем примере количество секунд задается равным нулю, что фактически отключает период охлаждения. Разогретые TLS-соединения сохраняют максимальный размер записи.

H2TLSCoolDownSecs 0

Директива H2TLSWarmUpSize

H2TLSWarmUpSize amount

H2TLSWarmUpSize 1048576

Эта директива задает количество байтов, которые передаются небольшими записями TLS (около 1300 байт), прежде чем для соединений https: HTTP/2 начнут использоваться записи максимального размера (16 КБ). Ее можно использовать для всего сервера или для отдельных <VirtualHost>.

Измерения, проведенные лабораторией производительности Google, показывают, что максимальная производительность TLS-соединений достигается, если размер начальных записей не превышает MTU, чтобы полная запись помещалась в IP-пакет.

Пока TCP адаптирует управление потоком и размеры окна, более длинные записи TLS могут застревать в очередях или теряться, что требует их повторной передачи. Разумеется, это справедливо для всех пакетов. Однако TLS необходима запись целиком, чтобы расшифровать ее. Отсутствие любых байтов в конце приостанавливает использование уже полученных данных.

После успешной отправки достаточного количества байтов состояние TCP-соединения стабилизируется, и для оптимальной производительности можно использовать записи TLS максимального размера (16 КБ).

В средах, где серверы доступны локально или только через надежные соединения, значение можно уменьшить; значение 0 полностью отключает этап разогрева.

В следующем примере размер задается равным нулю, что фактически отключает этап разогрева.

H2TLSWarmUpSize 0

Директива H2Upgrade

H2Upgrade on|off

H2Upgrade on for h2c, off for h2 protocol

Эта директива включает или отключает использование метода Upgrade в HTTP/1.1 для переключения на HTTP/2. Для включения переключения на HTTP/2 в данном виртуальном хосте директиву следует использовать внутри секции <VirtualHost>.

Этот способ переключения протоколов определен в HTTP/1.1 и использует заголовок "Upgrade" (отсюда и название), чтобы сообщить о готовности использовать другой протокол. Это может происходить при любом запросе в соединении HTTP/1.1.

Этот способ переключения протоколов по умолчанию включен для незашифрованных соединений (возможный h2c) и отключен для TLS (возможный h2), как предписывает RFC 7540.

Обратите внимание: переключение принимается только для запросов без тела. Запросы POST и PUT с содержимым никогда не приведут к переключению на HTTP/2. Альтернативу Upgrade см. в H2Direct.

Этот режим действует только при включенном h2 или h2c с помощью Protocols.

H2Upgrade on

Директива H2WebSockets

H2WebSockets on|off

H2WebSockets off

Используйте H2WebSockets, чтобы включить или отключить установление соединений WebSockets через протокол HTTP/2. Это расширение протокола определено в RFC 8441.

Такие запросы отправляются методом CONNECT с дополнительным заголовком ':protocol'. Внутри модуля такие запросы преобразуются в эквивалентные запросы HTTP/1.1 перед передачей на внутреннюю обработку.

Это означает, что WebSockets через HTTP/2 можно использовать в ProxyPass с параметром 'upgrade=websocket' без дополнительных изменений.

Модули сторонних разработчиков, обрабатывающие WebSockets непосредственно на сервере, также смогут использовать само установление протокола. Однако для передачи данных требуется дополнительная поддержка HTTP/2. Согласованное соединение WebSocket не сможет использовать сокет клиентского соединения для опроса событий ввода-вывода.

Поскольку включение этой функции может нарушить обратную совместимость с такими модулями сторонних разработчиков, по умолчанию она отключена.

Директива H2WindowSize

H2WindowSize bytes

H2WindowSize 65535

Эта директива задает размер окна, используемого для управления потоком данных от клиента к серверу, и ограничивает объем данных, которые сервер должен буферизовать. Клиент прекратит отправку данных в потоке после достижения ограничения, пока сервер не сообщит о появлении свободного места (после обработки части данных).

Это ограничение влияет только на тела запросов, но не на их метаданные, например заголовки. Кроме того, оно не влияет на тела ответов, поскольку размер окна для них регулируется клиентами.

H2WindowSize 128000