Upgrade
Request & response General

Overview

Upgrade proposes switching an already-open connection to a different protocol. On requests the client lists protocols it wants; on responses the server states the protocol it switched to.

Its most iconic use is upgrading an HTTP connection to WebSocket, and it is always paired with `Connection: Upgrade`.

Details

The handshake goes: the client sends `Upgrade: websocket` and `Connection: Upgrade`; if the server accepts it replies `101 Switching Protocols` and, from that point, turns the same TCP connection into WebSocket frame communication. Upgrade is a hop-by-hop header, so it must be listed in Connection, and proxies must understand it for the upgrade to succeed.

Beyond WebSocket it was used to raise plaintext HTTP/1.1 to unencrypted HTTP/2 via `h2c` (HTTP/2 cleartext). But browsers don't support h2c Upgrade and HTTP/2 is negotiated over TLS (ALPN) in practice, so today Upgrade is mostly WebSocket. `Upgrade: TLS/1.0` (RFC 2817), which meant switching to TLS, is also essentially unused.

When a server requires an upgrade to a particular protocol (e.g. HTTPS) it responds `426 Upgrade Required`, naming the required protocol in the Upgrade header. For security, proxies and gateways that mishandle Upgrade can cause request smuggling or connection confusion, so a reverse proxy's WebSocket pass-through configuration (forwarding the Upgrade/Connection headers) must be exact.

Syntax

Upgrade: <protocol>[/<version>][, ...]

e.g. Upgrade: websocket

Notes

Related headers

ConnectionSec-WebSocket-KeySec-WebSocket-Accept

Related status codes

Specification