Special and protected headers
Special and Protected Headers
This document lists and explains headers that have special meaning to Fastly (or in HTTP/1.1), their purpose, and whether they can be modified.
Protected headers
Protected headers are headers that have special meaning in HTTP/1.1. User modification of these headers can cause protocol breakage, so they may not be modified by users. This protection is enforced at compile-time: a VCL that attempts modification of these headers will simply fail to compile.
The headers:
- Content-Length
- Content-Range
- Expect
- Fastly-FF
- Proxy-Authenticate
- Proxy-Authorization
- TE
- Trailer
- Transfer-encoding
- Upgrade
Special headers
Fastly injects a number of special headers in a number of places (in the System VCL, in the templates that generate customer VCLs and in the Varnish code itself). This page enumerates these headers and explains them.
Fastly-Backend
When present in a clustering request, the value of this header represents the name of an origin director to use if the cluster request results in a miss on the cluster node.
Fastly-Cachetype
Describes whether the request resulted in a cache hit / miss / pass / etc.
Fastly-Check-SHA1
A header that, if set, allows the request to see if the particular digest exists in the local cache.
Fastly-Client-IP
This represents the IP of the client that has initiated the request to Fastly. In case the request was served by SSL, the daemon serving SSL sets this header.
Fastly-Cookie-Overflow
When a cookie header exceeds 32768 bytes, the cookie is stripped. In this case,
we set the Fastly-Cookie-Overflow header so that the customer can take action
on such requests.
Fastly-Debug-Path
Contains information about which nodes handled fetching and delivery of an object, as well as object TTL information.
Fastly-Digest
When servicing a PURGE request, this header represents the SHA-256 hash of
the object to be purged.
Fastly-Digest-Get
When this header is present in a cluster request, this specifies the SHA-256 hash of the object we're attempting to fetch.
Fastly-Digest-No-Insert
When present in request headers, this prevents an object from being entered into the cache and results in an error if the request was a miss.
Fastly-FF
This header enumerates a list of Fastly cache nodes that any particular request was received over. This aids us in loop detection, among other things.
Fastly-Force-Shield
Forces a request to perform clustering, even if it wouldn't have otherwise.
Fastly-GeoIP-Hack-Test
Logs debugging output when attempting to resolve the client IP using other Fastly headers.
Fastly-Hit
This header is set to 1 when a cluster request resolved in a hit.
Fastly-Host
When set, this header is preferred over the Host header for identifying the
service for this particular request.
Fastly-Max-Failover-Depth
This header field indicates to a cache about to fetch an object from another
cache through clustering that this cache should instead fail the request with a
503 if this cache does not consider itself to be the primary cache for this
object when Fastly-Max-Failover-Depth: 0, or the primary or secondary cache
for this object when Fastly-Max-Failover-Depth: 1.
This field was introduced to support Gondola.
Fastly-No-Origin
When this header is present, a request that results in communicating with the origin results in an error.
Fastly-No-Shield
When this header field is present in a request, clustering will be disabled. This header field does not influence what we now call shielding. The name is confusing for historic reasons.
Fastly-Pass
This header is set to 1 when a cluster request resolved in a pass.
Fastly-SSL
This header is set when a request to Fastly was received over SSL.
Fastly-Server-IP
When setting the client IP for a SSL request, this header represents the IP address of the server that received the request.
Fastly-Server-Port
When setting the client IP for a SSL request, this header represents the port the server received the request on. If it is not present, the default value is set to "443".
Fastly-Service
Sent by the SSL server when handling a request for a customer with a dedicated IP. This is used when assigning the service ID for a request. This particular header is only needed when Apache is serving SSL.
Fastly-Service-Id
The service ID this request belongs to. This is used to authenticate requests to the API.
Fastly-Shield
This header is used in clustering responses to transmit information about an object resolved through a cluster request.
Fastly-Shield-Error
When a clustering request results in an error on the cluster node, this header is sent back to the edge node.
Fastly-Shield-Flags
This header is set on clustering requests and contains information about the state of the environment (such as acceptable TTLs) when the request was made. The cluster node is then responsible for honoring the request within the constraints specified by these flags.
Fastly-Shield-Restart
When present, this header signifies to an edge node that a cluster request resulted in a restart and that the edge node should restart the VCL state machine.
Fastly-Shield-Server
The presence of this header allows clustering requests to break ties between edge and cluster nodes collapsing requests for an object. Without this header, it's possible that nodes enter a livelock state where requests for an object have no definitive owner and thus are placed on the waiting list forever.
Fastly-Stream-Miss
The presence of this header forces stream-on-miss behavior when possible. (Other constraints, like an SSL backend or gzipping may negate the ability to initiate this behavior.)
Fastly-Surrogate-Key
When a surrogate key purge is requested, this header is set to represent the key we were requested to purge.
Fastly-TTL
When present in a cluster request, this specifies the ttl for an object. This
header is superceded by Fastly-Shield-Flags and is deprecated.
Fastly-Tmp-Obj-Grace
Because obj.grace isn't available in vcl_deliver, we stash this information
such that it can be logged there.
Fastly-Tmp-Obj-TTL
Because obj.ttl isn't available in vcl_deliver, we stash this information
such that it can be logged there.
Fastly-Vary-String
Provides a basis for Varying on an object, even when no Vary string is supplied by the origin. This allows testing of Vary functionality.
Purge-Host
When a HTTP request with a PURGE method is received, and that request did not
come from localhost, this header is set to the original value of the Host
header.
Surrogate-Key
When sent by a backend for an object, or set in vcl_fetch, this header
specifies a set of keys that may be used to purge the object.
X-Timer
A header that contains timing information about VCL state transitions.
X-Varnish
An advertisement.
X-Varnish-Client
When we are performing a shielding or clustering request, X-Varnish-Client is
set to provide information that the request was sourced by a Fastly Varnish.
