Reference manual for squid's configuraiton directives
| Index | Alphabetical Index |
http_upgrade_request_protocols
Controls client-initiated and server-confirmed switching from HTTP to
another protocol (or to several protocols) using HTTP Upgrade mechanism
defined in RFC 7230 Section 6.7. Squid itself does not understand the
protocols being upgraded to and participates in the upgraded
communication only as a dumb TCP proxy. Admins should not allow
upgrading to protocols that require a more meaningful proxy
participation.
Usage: http_upgrade_request_protocols <protocol> allow|deny [!]acl ...
The required "protocol" parameter is either an all-caps word OTHER or an
explicit protocol name (e.g. "WebSocket") optionally followed by a slash
and a version token (e.g. "HTTP/3"). Explicit protocol names and
versions are case sensitive.
When an HTTP client sends an Upgrade request header, Squid iterates over
the client-offered protocols and, for each protocol P (with an optional
version V), evaluates the first non-empty set of
http_upgrade_request_protocols rules (if any) from the following list:
* All rules with an explicit protocol name equal to P.
* All rules that use OTHER instead of a protocol name.
In other words, rules using OTHER are considered for protocol P if and
only if there are no rules mentioning P by name.
If both of the above sets are empty, then Squid removes protocol P from
the Upgrade offer.
If the client sent a versioned protocol offer P/X, then explicit rules
referring to the same-name but different-version protocol P/Y are
declared inapplicable. Inapplicable rules are not evaluated (i.e. are
ignored). However, inapplicable rules still belong to the first set of
rules for P.
Within the applicable rule subset, individual rules are evaluated in
their configuration order. If all ACLs of an applicable "allow" rule
match, then the protocol offered by the client is forwarded to the next
hop as is. If all ACLs of an applicable "deny" rule match, then the
offer is dropped. If no applicable rules have matching ACLs, then the
offer is also dropped. The first matching rule also ends rules
evaluation for the offered protocol.
If all client-offered protocols are removed, then Squid forwards the
client request without the Upgrade header. Squid never sends an empty
Upgrade request header.
An Upgrade request header with a value violating HTTP syntax is dropped
and ignored without an attempt to use extractable individual protocol
offers.
Upon receiving an HTTP 101 (Switching Protocols) control message, Squid
checks that the server listed at least one protocol name and sent a
Connection:upgrade response header. Squid does not understand individual
protocol naming and versioning concepts enough to implement stricter
checks, but an admin can restrict HTTP 101 (Switching Protocols)
responses further using http_reply_access. Responses denied by
http_reply_access rules and responses flagged by the internal Upgrade
checks result in HTTP 502 (Bad Gateway) ERR_INVALID_RESP errors and
Squid-to-server connection closures.
If Squid sends an Upgrade request header, and the next hop (e.g., the
origin server) responds with an acceptable HTTP 101 (Switching
Protocols), then Squid forwards that message to the client and becomes
a TCP tunnel.
The presence of an Upgrade request header alone does not preclude cache
lookups. In other words, an Upgrade request might be satisfied from the
cache, using regular HTTP caching rules.
This clause only supports fast acl types.
See https://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
Each of the following groups of configuration lines represents a
separate configuration example:
# never upgrade to protocol Foo; all others are OK
http_upgrade_request_protocols Foo deny all
http_upgrade_request_protocols OTHER allow all
# only allow upgrades to protocol Bar (except for its first version)
http_upgrade_request_protocols Bar/1 deny all
http_upgrade_request_protocols Bar allow all
http_upgrade_request_protocols OTHER deny all # this rule is optional
# only allow upgrades to protocol Baz, and only if Baz is the only offer
acl UpgradeHeaderHasMultipleOffers ...
http_upgrade_request_protocols Baz deny UpgradeHeaderHasMultipleOffers
http_upgrade_request_protocols Baz allow all
| Index | Alphabetical Index |