Mercurial > hg > nginx-site
diff xml/en/docs/http/websocket.xml @ 849:0ed4c093c026
WebSocket proxying howto.
author | Homutov Vladimir <vl@nginx.com> |
---|---|
date | Thu, 28 Feb 2013 11:20:28 +0400 |
parents | |
children | 95c3c3bbf1ce |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/en/docs/http/websocket.xml Thu Feb 28 11:20:28 2013 +0400 @@ -0,0 +1,82 @@ +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> + +<article name="WebSocket proxying" + link="/en/docs/http/websocket.html" + lang="en" + rev="1"> + + +<section> + +<para> +To turn a connection between a client and server from HTTP/1.1 into WebSocket, +the <link url="http://tools.ietf.org/html/rfc2616#section-14.42">protocol +switch</link> mechanism available in HTTP/1.1 is used. +</para> + +<para> +There is one subtlety however: since the <header>Upgrade</header> is a +<link url="http://tools.ietf.org/html/rfc2616#section-13.5.1">hop-by-hop</link> +header, it is not passed from a client to proxied server. +With forward proxying, clients may use the <literal>CONNECT</literal> +method to circumvent this issue. +This does not work with reverse proxying however, +since clients are not aware of any proxy servers, +and special processing on a proxy server is required. +</para> + +<para> +Since version 1.3.13, +nginx implements special mode of operation +that allows to set up a tunnel between a client and proxied +server if the proxied server returned a response with the code +<http-status code="101" text="Switching Protocols"/>, +and the client asked for a protocol switch via the <header>Upgrade</header> +header in a request. +</para> + +<para> +As noted above, hop-by-hop headers including <header>Upgrade</header> +and <header>Connection</header> are not passed from a client to proxied +server, therefore in order for the proxied server to know about the client’s +intention to switch a protocol to WebSocket, these headers have to be +passed explicitly: +<programlisting> +location /chat/ { + proxy_pass http://backend; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; +} +</programlisting> +A more sophisticated example +in which a value of the <header>Connection</header> header field +in a request to the proxied server depends on the presence of +the <header>Upgrade</header> field in the client request header: +<programlisting> +http { + map $http_upgrade $connection_upgrade { + default upgrade; + '' close; + } + + server { + ... + + location /chat/ { + proxy_pass http://backend; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + } + } +</programlisting> +</para> + +</section> + +</article>