HTTP2-Settings
The HTTP HTTP2-Settings request header carries HTTP/2 connection parameters during an Upgrade from HTTP/1.1 to HTTP/2.
Deprecated
The HTTP/2 specification explicitly deprecates the h2c cleartext upgrade mechanism and the HTTP2-Settings header as well. The IANA HTTP header registry lists HTTP2-Settings as Obsoleted. Most HTTP/2 deployments use TLS-based negotiation via ALPN instead of h2c upgrade.
Usage
The HTTP2-Settings header is part of the HTTP/2
cleartext upgrade mechanism (h2c). When a client
sends an Upgrade request to switch from
HTTP/1.1 to HTTP/2, the
HTTP2-Settings header supplies the initial
SETTINGS frame parameters the HTTP/2 connection
will use.
The value is a base64url-encoded payload of an HTTP/2 SETTINGS frame. This encoding allows binary frame data to travel safely in an HTTP/1.1 header field. The server decodes and applies these settings once the upgrade completes.
The server does not explicitly acknowledge the
HTTP2-Settings header. A successful upgrade is
confirmed when the server responds with
101 Switching Protocols and includes
Upgrade: h2c in the response.
A request containing more than one HTTP2-Settings
header is malformed. The server rejects the upgrade
in this case. The Connection header
for the upgrade request lists both Upgrade and
HTTP2-Settings as hop-by-hop fields, ensuring
intermediaries do not forward them.
Note
An empty string is a valid value for the HTTP2-Settings header. This signals default HTTP/2 settings with no custom parameters.
Example
A client initiates an HTTP/2 cleartext upgrade. The base64url string encodes the desired HTTP/2 SETTINGS frame parameters, such as initial window size and maximum concurrent streams.
GET / HTTP/1.1
Host: example.re
Connection: upgrade, HTTP2-Settings
Upgrade: h2c
HTTP2-Settings: AAMAAABkAAQCAAAAAAIAAAAA
The server accepts the upgrade and responds with 101 Switching Protocols. From this point, both parties communicate using the HTTP/2 protocol.
HTTP/1.1 101 Switching Protocols
Connection: upgrade
Upgrade: h2c
A minimal upgrade request with an empty settings payload uses default HTTP/2 parameters.
GET / HTTP/1.1
Host: example.re
Connection: upgrade, HTTP2-Settings
Upgrade: h2c
HTTP2-Settings:
Takeaway
The HTTP2-Settings header delivers base64url- encoded HTTP/2 SETTINGS frame data during a cleartext Upgrade from HTTP/1.1, establishing the connection parameters for the new protocol session.