apache-http-server/docs/manual/mod/mod_proxy_wstunnel.xml.fr

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
<!-- English Revision: 1907040 -->
<!-- French translation : Lucien GENTIS -->

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<modulesynopsis metafile="mod_proxy_wstunnel.xml.meta">

<name>mod_proxy_wstunnel</name>
<description>Module pour <module>mod_proxy</module> supportant les
websockets</description>
<status>Extension</status>
<sourcefile>mod_proxy_wstunnel.c</sourcefile>
<identifier>proxy_wstunnel_module</identifier>
<compatibility>Disponible à partir de la version 2.4.5 du serveur HTTP
Apache</compatibility>

<summary>
  <note type="warning"><title><a id="deprecation"
  name="deprecation">Obsolescence</a></title>
    <p>Depuis la version 2.4.47 du serveur HTTP Apache, la promotion de
    protocole (tunneling) peut être pris en charge de manière plus efficace par
    <module>mod_proxy_http</module>.</p>
    <p>Voir <a href="mod_proxy.html#protoupgrade">Promotion de protocole</a>.</p>
  </note>

    <p>Pour utiliser ce module, <module>mod_proxy</module> doit être
    chargé. Il fournit le support du tunnelling pour les connexions
    websocket vers un serveur websockets d'arrière-plan. La connexion
    est automatiquement promue en connexion websocket :</p>

    <example><title>Réponse HTTP</title>
        <highlight language="config">
Upgrade: WebSocket
Connection: Upgrade
        </highlight>
    </example>

<p>Le mandatement des requêtes vers un serveur websockets comme
<code>echo.websocket.org</code> peut être configuré via la directive <directive
type="ProxyPass" module="mod_proxy">ProxyPass</directive> :</p>
    <highlight language="config">
ProxyPass "/ws2/"  "ws://echo.websocket.org/"
ProxyPass "/wss2/" "wss://echo.websocket.org/"
    </highlight>
    
<p>Il est possible de mandater les websockets et HTTP en même temps en
définissant la directive <directive type="ProxyPass"
module="mod_proxy">ProxyPass</directive> concernant les websockets avant celle
concernant HTTP :</p>
    <highlight language="config">
ProxyPass "/"  "ws://backend.example.com:9080/"
ProxyPass "/"  "http://backend.example.com:9080/"
    </highlight>

<p>La répartition de charge entre plusieurs serveurs d'arrière-plan peut être
configurée via le module <module>mod_proxy_balancer</module>.</p>

<p>
Ce module peut aussi être utilisé pour la promotion vers des protocoles autres
que WebSocket en définissant le paramètre <var><a
href="mod_proxy.html#upgrade">upgrade</a></var> de la directive <directive
type="ProxyPass" module="mod_proxy">ProxyPass</directive> avec un nom de
protocole particulier.
Les valeurs spéciales <code>upgrade=NONE</code> et <code>upgrade=ANY</code>
peuvent être utilisées pour tester ou forcer la promotion de protocole mais leur
utilisation <strong>n'est pas recommandée</strong> en production pour des
raisons de sécurité.
<code>NONE</code> signifie que la vérification de l'en-tête est omise mais que
la promotion (tunneling) vers WebSocket s'effectuera quand-même.
<code>ANY</code> signifie que la promotion (tunneling) s'effectuera en utilisant
tout protocole demandé par le client.
</p>
</summary>

<seealso><module>mod_proxy</module></seealso>

<directivesynopsis>
<name>ProxyWebsocketFallbackToProxyHttp</name>
<description>Demande à ce module de laisser <module>mod_proxy_http</module>
gérer la requête</description>
<syntax>ProxyWebsocketFallbackToProxyHttp On|Off</syntax>
<default>ProxyWebsocketFallbackToProxyHttp On</default>
<contextlist><context>server config</context>
<context>virtual host</context>
</contextlist>
<compatibility>Disponible à partir de la version 2.4.48 du serveur HTTP Apache</compatibility>

<usage>
    <p>Depuis la version 2.4.47 de httpd, <module>mod_proxy_http</module> peut
    gérer le tunneling et la mise à jour via les WebSockets en accord avec la
    RFC 7230 ; cette directive permet de définir si, pour ces actions,
    <module>mod_proxy_wstunnel</module> doit passer la main à
    <module>mod_proxy_http</module>, ce qui est le cas par défaut.</p>
    <p>Définir cette directive à <em>Off</em> revient à laisser
    <module>mod_proxy_wstunnel</module> gérer les requêtes WebSocket, comme avec
    les versions 2.4.46 et antérieures de httpd.</p>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>ProxyWebsocketAsync</name>
<description>Création d'un tunnel asynchrone</description>
<syntax>ProxyWebsocketAsync ON|OFF</syntax>
<contextlist><context>server config</context>
<context>virtual host</context>
</contextlist>

<usage>
    <p>Cette directive permet d'imposer la création d'un tunnel
    asynchrone. Si le module MPM utilisé ne supporte pas les
    fonctionnalités nécessaires, le tunnel est créé en mode synchrone.</p>
    <note><title>Note</title><p>Le support du mode asynchrone est
    au stade expérimental et est susceptible d'évoluer.</p></note>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>ProxyWebsocketIdleTimeout</name>
<description>Temps d'attente maximum pour des données sur le tunnel websockets</description>
<syntax>ProxyWebsocketIdleTimeout <var>num</var>[ms]</syntax>
<default>ProxyWebsocketIdleTimeout 0</default>
<contextlist><context>server config</context>
<context>virtual host</context>
</contextlist>

<usage>
    <p>Cette directive permet de définir un temps maximum pendant lequel
    le tunnel pourra rester ouvert et inactif. Par défaut, ce temps est exprimé
    en secondes, mais vous pouvez le spécifier en millisecondes en utilisant le
    suffixe <em>ms</em>.</p>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>ProxyWebsocketAsyncDelay</name>
<description>Temps d'attente synchrone maximum pour des données</description>
<syntax>ProxyWebsocketAsyncDelay <var>num</var>[ms]</syntax>
<default>ProxyWebsocketAsyncDelay 0</default>
<contextlist><context>server config</context>
<context>virtual host</context>
</contextlist>

<usage>
    <p>Si la directive <directive>ProxyWebsocketAsync</directive> est
    activée, cette directive permet de définir le temps maximum pendant lequel
    le serveur attendra des données en mode synchrone. Par défaut, ce temps est exprimé
    en secondes, mais vous pouvez le spécifier en millisecondes en utilisant le
    suffixe <em>ms</em>.</p>

    <note><title>Note</title><p>Le support du mode asynchrone est
    au stade expérimental et est susceptible d'évoluer.</p></note>
</usage>
</directivesynopsis>

</modulesynopsis>