Mercurial > hg > nginx-site
annotate xml/en/docs/http/websocket.xml @ 2503:2d0b563c205c
Updated with Netcraft February 2020 Web Server Survey stats.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Fri, 21 Feb 2020 10:57:48 +0000 |
parents | 66a30a380fba |
children | 4add6ae1296f |
rev | line source |
---|---|
849 | 1 <!-- |
2 Copyright (C) Nginx, Inc. | |
3 --> | |
4 | |
5 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> | |
6 | |
7 <article name="WebSocket proxying" | |
8 link="/en/docs/http/websocket.html" | |
9 lang="en" | |
1923
66a30a380fba
Fixed links to tools.ietf.org.
Ruslan Ermilov <ru@nginx.com>
parents:
1536
diff
changeset
|
10 rev="4"> |
849 | 11 |
12 | |
13 <section> | |
14 | |
15 <para> | |
16 To turn a connection between a client and server from HTTP/1.1 into WebSocket, | |
1923
66a30a380fba
Fixed links to tools.ietf.org.
Ruslan Ermilov <ru@nginx.com>
parents:
1536
diff
changeset
|
17 the <link url="https://tools.ietf.org/html/rfc2616#section-14.42">protocol |
849 | 18 switch</link> mechanism available in HTTP/1.1 is used. |
19 </para> | |
20 | |
21 <para> | |
22 There is one subtlety however: since the <header>Upgrade</header> is a | |
1923
66a30a380fba
Fixed links to tools.ietf.org.
Ruslan Ermilov <ru@nginx.com>
parents:
1536
diff
changeset
|
23 <link url="https://tools.ietf.org/html/rfc2616#section-13.5.1">hop-by-hop</link> |
849 | 24 header, it is not passed from a client to proxied server. |
25 With forward proxying, clients may use the <literal>CONNECT</literal> | |
26 method to circumvent this issue. | |
27 This does not work with reverse proxying however, | |
28 since clients are not aware of any proxy servers, | |
29 and special processing on a proxy server is required. | |
30 </para> | |
31 | |
32 <para> | |
33 Since version 1.3.13, | |
34 nginx implements special mode of operation | |
966 | 35 that allows setting up a tunnel between a client and proxied |
849 | 36 server if the proxied server returned a response with the code |
37 <http-status code="101" text="Switching Protocols"/>, | |
38 and the client asked for a protocol switch via the <header>Upgrade</header> | |
39 header in a request. | |
40 </para> | |
41 | |
42 <para> | |
43 As noted above, hop-by-hop headers including <header>Upgrade</header> | |
44 and <header>Connection</header> are not passed from a client to proxied | |
45 server, therefore in order for the proxied server to know about the client’s | |
46 intention to switch a protocol to WebSocket, these headers have to be | |
47 passed explicitly: | |
48 <programlisting> | |
49 location /chat/ { | |
50 proxy_pass http://backend; | |
51 proxy_http_version 1.1; | |
52 proxy_set_header Upgrade $http_upgrade; | |
53 proxy_set_header Connection "upgrade"; | |
54 } | |
55 </programlisting> | |
56 A more sophisticated example | |
57 in which a value of the <header>Connection</header> header field | |
58 in a request to the proxied server depends on the presence of | |
59 the <header>Upgrade</header> field in the client request header: | |
60 <programlisting> | |
61 http { | |
62 map $http_upgrade $connection_upgrade { | |
63 default upgrade; | |
64 '' close; | |
65 } | |
66 | |
67 server { | |
68 ... | |
69 | |
70 location /chat/ { | |
71 proxy_pass http://backend; | |
72 proxy_http_version 1.1; | |
73 proxy_set_header Upgrade $http_upgrade; | |
74 proxy_set_header Connection $connection_upgrade; | |
75 } | |
76 } | |
77 </programlisting> | |
78 </para> | |
79 | |
1525
e47758a54759
Updated the "WebSockets Proxying" article with proxy_read_timeout.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
966
diff
changeset
|
80 <para> |
e47758a54759
Updated the "WebSockets Proxying" article with proxy_read_timeout.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
966
diff
changeset
|
81 By default, the connection will be closed |
1536
d1d49bbb3df0
Removed proxy_send_timeout and its example from "WebSockets Proxying" article.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1525
diff
changeset
|
82 if the proxied server does not transmit any data within 60 seconds. |
d1d49bbb3df0
Removed proxy_send_timeout and its example from "WebSockets Proxying" article.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1525
diff
changeset
|
83 This timeout can be increased with the |
d1d49bbb3df0
Removed proxy_send_timeout and its example from "WebSockets Proxying" article.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1525
diff
changeset
|
84 <link doc="ngx_http_proxy_module.xml" id="proxy_read_timeout"/> directive. |
d1d49bbb3df0
Removed proxy_send_timeout and its example from "WebSockets Proxying" article.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1525
diff
changeset
|
85 Alternatively, the proxied server can be configured |
d1d49bbb3df0
Removed proxy_send_timeout and its example from "WebSockets Proxying" article.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1525
diff
changeset
|
86 to periodically send WebSocket ping frames to reset the timeout |
d1d49bbb3df0
Removed proxy_send_timeout and its example from "WebSockets Proxying" article.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1525
diff
changeset
|
87 and check if the connection is still alive. |
1525
e47758a54759
Updated the "WebSockets Proxying" article with proxy_read_timeout.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
966
diff
changeset
|
88 </para> |
e47758a54759
Updated the "WebSockets Proxying" article with proxy_read_timeout.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
966
diff
changeset
|
89 |
849 | 90 </section> |
91 | |
92 </article> |