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. Usermodification of these headers can cause protocol breakage, so they may not bemodified by users. This protection is enforced at compile-time: a VCL thatattempts 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 thename of an origin director to use if the cluster request results in a miss onthe 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 digestexists 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 thisheader.
Fastly-Cookie-Overflow
When a cookie header exceeds 32768 bytes, the cookie is stripped. In this case,we set theFastly-Cookie-Overflow header so that the customer can take actionon such requests.
Fastly-Debug-Path
Contains information about which nodes handled fetching and delivery of anobject, as well as object TTL information.
Fastly-Digest
When servicing aPURGE request, this header represents the SHA-256 hash ofthe object to be purged.
Fastly-Digest-Get
When this header is present in a cluster request, this specifies the SHA-256hash of the object we're attempting to fetch.
Fastly-Digest-No-Insert
When present in request headers, this prevents an object from being enteredinto 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 requestwas 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-Hit
This header is set to 1 when a cluster request resolved in a hit.
Fastly-Host
When set, this header is preferred over theHost header for identifying theservice for this particular request.
Fastly-Max-Failover-Depth
This header field indicates to a cache about to fetch an object from anothercache through clustering that this cache should instead fail the request with a503 if this cache does not consider itself to be the primary cache for thisobject whenFastly-Max-Failover-Depth: 0, or the primary or secondary cachefor this object whenFastly-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 theorigin 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 nameis 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 IPaddress of the server that received the request.
Fastly-Server-Port
When setting the client IP for a SSL request, this header represents the portthe server received the request on. If it is not present, the default valueis set to "443".
Fastly-Service
Sent by the SSL server when handling a request for a customer with a dedicatedIP. This is used when assigning the service ID for a request. This particularheader is only needed when Apache is serving SSL.
Fastly-Service-Id
The service ID this request belongs to. This is used to authenticate requeststo the API.
Fastly-Shield
This header is used in clustering responses to transmit information about anobject resolved through a cluster request.
Fastly-Shield-Error
When a clustering request results in an error on the cluster node, this headeris sent back to the edge node.
Fastly-Shield-Flags
This header is set on clustering requests and contains information about thestate of the environment (such as acceptable TTLs) when the request was made.The cluster node is then responsible for honoring the request within theconstraints specified by these flags.
Fastly-Shield-Restart
When present, this header signifies to an edge node that a cluster requestresulted in a restart and that the edge node should restart the VCL statemachine.
Fastly-Shield-Server
The presence of this header allows clustering requests to break ties betweenedge and cluster nodes collapsing requests for an object. Without this header,it's possible that nodes enter a livelock state where requests for an objecthave 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 toinitiate this behavior.)
Fastly-Surrogate-Key
When a surrogate key purge is requested, this header is set to represent thekey we were requested to purge.
Fastly-TTL
When present in a cluster request, this specifies the ttl for an object. Thisheader is superceded byFastly-Shield-Flags and is deprecated.
Fastly-Tmp-Obj-Grace
Becauseobj.grace isn't available invcl_deliver, we stash this informationsuch that it can be logged there.
Fastly-Tmp-Obj-TTL
Becauseobj.ttl isn't available invcl_deliver, we stash this informationsuch that it can be logged there.
Fastly-Vary-String
Provides a basis for Varying on an object, even when no Vary string is suppliedby the origin. This allows testing of Vary functionality.
Purge-Host
When a HTTP request with aPURGE method is received, and that request did notcome from localhost, this header is set to the original value of theHostheader.
Surrogate-Key
When sent by a backend for an object, or set invcl_fetch, this headerspecifies 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 isset to provide information that the request was sourced by a Fastly Varnish.
