<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!-- $LastChangedRevision$ -->

<!--
 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>Websockets support module for
<module>mod_proxy</module></description>
<status>Extension</status>
<sourcefile>mod_proxy_wstunnel.c</sourcefile>
<identifier>proxy_wstunnel_module</identifier>
<compatibility>Available in httpd 2.4.5 and later</compatibility>

<summary>
    <p>This module <em>requires</em> the service of <module
    >mod_proxy</module>. It provides support for the tunnelling of web
    socket connections to a backend websockets server. The connection
    is automatically upgraded to a websocket connection:</p>

    <example><title>HTTP Response</title>
        <highlight language="config">
Upgrade: WebSocket
Connection: Upgrade
        </highlight>
    </example>

<p>Proxying requests to a websockets server like <code>echo.websocket.org</code> can be done using the
<directive type="ProxyPass" module="mod_proxy">ProxyPass</directive> directive:</p>
    <highlight language="config">
ProxyPass "/ws2/"  "ws://echo.websocket.org/"
ProxyPass "/wss2/" "wss://echo.websocket.org/"
    </highlight>

<p>Load balancing for multiple backends can be achieved using <module>mod_proxy_balancer</module>.</p>

<p>In fact the module can be used to upgrade to other protocols, you can set the <code>upgrade</code>
parameter in the <directive type="ProxyPass" module="mod_proxy">ProxyPass</directive>
directive to allow the module to accept other protocol.
NONE means you bypass the check for the header but still upgrade to WebSocket.
ANY means that <code>Upgrade</code> will read in the request headers and use
in the response <code>Upgrade</code></p>
</summary>

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