1. Home
2. Guides
3. Core concepts

When Fastly makes requests to your origin servers, those requests may come from any of our POPs, which act independently. However, if you wish, you may designate one POP location as a 'shield', collecting requests from across the Fastly network. In this arrangement, requests to your origin server will come only from the designated shield POP, and all other Fastly locations will forward requests to the shield.

Shielding has significant benefits:

• Reduces origin load: reduces the volume of requests from Fastly to your origin servers
• Improves cache hit ratio (CHR): increases the probability of end user requests resulting in a cache HIT (albeit potentially not from the first POP which handles the request)
• Speeds up connections: reduces connection setup latency for MISS and PASS requests that must be served from origin (this feels counter-intuitive, but takes advantage of the fact that all Fastly POPs always have a pool of open connections to all other Fastly POPs, reducing the time required for costly multi-roundtrip handshakes).

Enabling and disabling shielding

Shielding may be enabled when adding or editing an origin server, and may be selected per-origin. If your origin servers are in different locations, it may make sense to choose different shields for each origin server. You can enable shielding via the web interface, or set the shield property of a Backend object when you create or modify it using the API or CLI. For example:

$ fastly backend create --name=app_server --address=192.168.123.123 --shield=amsterdam-nl --service-id=9yqrXWr5kfqroswtmxgQDz --version=latest
SUCCESS: Created backend app_server (service 9yqrXWr5kfqroswtmxgQDz version 1)

Each POP has a shield identifier. These are listed in the properties returned from the /pops API endpoint. For example, the POP in Amsterdam has the name AMS but a shield identifier of amsterdam-nl. See choosing a shield location.

Effects of shielding

Enabling shielding on a Fastly service will create side effects that should be considered carefully.

Double execution

Services using shielding will (in many cases) execute their edge code twice: once at the edge location and once at the shield location. However, if a request is received directly at the shield location, then any backend requests will go directly to your origin, so the edge code will only execute once.

req.backend.is_origin and req.backend.is_shield tell you whether a backend request made from the current POP will go to your origin server or to a shield POP, which is usually important when manipulating a request. fastly.ff.visits_this_service tells you whether the current POP is acting as a shield POP or not, which is more often important when manipulating a response.

For example, use req.backend.is_origin to determine whether to modify request headers before forwarding a request to an origin:

if (req.backend.is_origin) {
  set req.http.host = "example.com";
}

But use fastly.ff.visits_this_service to determine whether to modify response headers before delivering a response:

if (fastly.ff.visits_this_service == 0) {
  set resp.http.Cache-Control = "no-store, private";
}

Both of these conditionals will ensure that the associated logic only runs once. Here are some more examples of operations typically associated with one or the other phase:

Be aware that changes made to a response at a shield POP will be viewed by an edge POP as if they are part of the response from the origin. Therefore any changes you want to make to a response just before serving it to the browser should be done only on the edge.

if (req.url.path !~ "^/bucket-name/") {
  set req.url = "/bucket-name/" + req.url;
}

No VCL-defined backends

For VCL services, it is possible to define backends using VCL code as well as via the web interface, API or CLI. However, you cannot apply shielding to origins that you define in VCL.

Host header gotchas

Fastly uses the HTTP Host header on inbound requests to select the correct service to handle the request. If the Host header doesn't match a known customer domain an HTTP 500 (Internal Server Error) response is served to the end user.

If you change the value of req.http.host as part of your edge code and it executes at the edge POP, then be aware that Fastly may not be able to trigger the correct service when the request arrives at the shield POP. Either manipulate the Host header only when the request is known to be going to your own origin (see req.backend.is_origin), or use the override_host property when creating the backend (and don't modify req.http.host in VCL). The latter option is often the most conceptually straightforward and least prone to error.

Client IP inaccuracy

Requests that have come from another Fastly POP will report the IP of the source POP as client.ip in VCL. To reliably access the true client IP, use the Fastly-provided Fastly-Client-IP header.

set client.identity = req.http.Fastly-Client-IP;

Cache hit ratio (CHR) inaccuracy

If a request results in a MISS at an edge POP and is forwarded to a shield POP where it finds a HIT, the user is ultimately served from cache, but we will record both the miss and the hit for the purpose of calculating your cache hit ratio. While 'shield hits' will involve more latency for end users than 'edge hits', the hit will still mean there is no need for an origin request. Equally, a request that does reach your origin server will be counted as two misses, one at the edge, and one at the shield.

This will result in a cache hit ratio that may be lower than you expect. Since there are multiple ways of calculating CHR on shielded configurations, you may like to use our historical stats API to get raw numbers and perform your own calculations.

Backend assignment in VCL

If you wish to write custom VCL logic for assigning a backend to a request (i.e. set req.backend = backend_name;), and that backend is shielded, see multiple backends, to avoid overriding (or being overridden by) the generated shield routing logic.

Billing implications

Traffic from one Fastly POP to another will count towards your request count and billable bandwidth. In the most extreme case, if your service is configured to PASS every request, then your request count and delivery bandwidth will almost double, since most requests will be presented to two Fastly POPs, but in more realistic scenarios, shielding will often reduce costs overall. See our guide in documentation for more information.

Advanced shielding scenarios

Shielding can be used in many different configurations and variations. Some of the most common include:

Multiple backends

If you have multiple backends (for example because you are performing load balancing, have origin servers serving different regions, or a microservices architecture), then each backend must have shielding configured independently.

Configure each backend with the shield location that is most appropriate for its origin server, by setting the shield property to your chosen shield identifier. Backends may share the same shield POP or may shield in different locations, unless they have automatic load balancing enabled, in which case all backends must shield in the same location.

With multiple backends your service also requires some configuration to tell Fastly which backend to use. If you do not have custom VCL and use conditions or automatic load balancing to select backends, this happens automatically. However, if you want to use custom VCL to select an origin that is shielded, we recommend combining custom VCL with conditions:

1. Declare a custom local boolean variable per backend at the start of vcl_recv
2. Add a condition to each backend, which selects that backend if the matching variable is true, e.g., var.backend_a == true
3. Add custom backend selection logic before the #FASTLY placeholder in your VCL code (or using a VCL snippet)

For example:

declare local var.backend_a BOOL;
declare local var.backend_b BOOL;

if (req.url.path ~ "^/account(?:/.*)?\z") {
  set var.backend_a = true;
} else {
  set var.backend_b = true;
}

#FASTLY RECV

This way, Fastly is able to perform the backend selection (the code to do this will be generated and will replace the #FASTLY RECV placeholder), and will assign the shield POP or the actual origin server as appropriate, while still ultimately selecting the correct backend for the request based on your own logic.

Service pinning

If your service is pinned, then the domain the end user is connected to may not be explicitly attached to your service, because your service will answer any request that resolves to your Fastly-assigned dedicated IP space and for which you have a TLS configuration. This can cause a problem when requests are forwarded from an edge POP to a shield POP, because the shield does not know which service to invoke. To resolve this, the service must set the HTTP Host header to a domain name that is explicitly associated with the service, before forwarding the request to the shield.

set bereq.http.host = if (
  req.backend.is_shield,
  "{some-name}.freetls.fastly.net", # A domain explicitly associated with your service, to allow shielding to work
  fastly_info.host_header           # The hostname to forward to your backend
);

You must also reinstate the original Host header on the shield POP so that both the edge and shield use the same Host value to look up the object in the cache.

Enable or disable shielding for a single request

If a shielded backend is selected and the current POP is not the designated shield POP, shielding will happen by default if req.restarts == 0 (i.e., the request has not been restarted). You can change this using a "recv" VCL snippet):

set var.fastly_req_do_shield = true;

You may want to do this to achieve use cases such as:

• Enable shielding even after a restart
• Disable shielding for certain URL paths which cannot be cached

var.fastly_req_do_shield is a custom VCL variable defined by Fastly's generated VCL. It's defined at the beginning of the #FASTLY RECV macro and affects the shielding decisions made at the end of #FASTLY RECV, so the only way to use it effectively is in a VCL snippet, because snippets are rendered within the #FASTLY RECV macro.

Debugging

Shielding increases the number of potential outcomes for a request presented to a Fastly edge. It's possible that the request will be answered directly from the edge POP. If the edge POP doesn't have the object, the request might still result in a cache HIT, but from the shield POP. Observing these effects and understanding how they affect your metrics can be a necessary step in debugging services with shielding enabled.

The X-Served-By, X-Cache-Hits and X-Cache response headers, which normally show only one entry without shielding enabled, will include an entry for each Fastly POP that has processed the request, but bear in mind that if a request is a HIT at the edge, the entry representing the shield POP will be from when the cached object was originally cached. First, start by understanding the possible values of X-Cache:

So, where the X-Cache header contains two entries and the second one is 'HIT', the first entry in each of the three debugging headers relates to when the object was originally fetched from the shield, not the current status of the object at the shield.

Additionally, the X-Cache-Hits header records the value of the obj.hits VCL variable, which is local to the individual cache node. To optimise and balance load, Fastly may cache objects on multiple machines in a POP, and particularly hot objects may end up cached on every node in the POP (see clustering to learn more). As a result, where the second token of X-Cache is 'HIT', the first token of X-Cache-Hits will refer to the number of hits recorded on the individual cache server at the shield POP at the time that the object was served from the shield to the edge. This can often be confusing.

Example response data

Imagine a request for an object that is not cached by Fastly, on a service with shielding enabled. The response would contain headers that look like this:

X-Cache: MISS, MISS
X-Served-By: cache-iad2120-IAD, cache-sjc3120-SJC
X-Cache-Hits: 0, 0

In this instance, the X-Cache: MISS, MISS shows that the request has transited two Fastly POPs and was not in the cache in either of them. X-Served-By lists the servers acting as the delivery node in each POP, in the order in which they processed the response. In this case, cache-iad2120-IAD (Dulles, Virginia) was the shield POP (closest to the backend), and therefore saw the response first, and cache-sjc3120-SJC (San Jose, California) was the edge POP (closest to the end user).

If the same request is made, moments later, by the same user on a still-open connection, it would be expected to be handled by exactly the same edge server:

X-Cache: MISS, HIT
X-Served-By: cache-iad2120-IAD, cache-sjc3120-SJC
X-Cache-Hits: 0, 1

This time, the request was a hit at the edge cache-node (cache-sjc3120-SJC). Because it is a hit at the edge it would not be forwarded to a shield. The MISS listed for cache-iad2120-IAD reflects the state of that node from the first request, and not its current state. The object is now cached in both POPs. Making a third request on the same connection would result in the same response except that X-Cache-Hits would now be 0, 2.

Requesting the object again on a fresh connection will likely result in the request being handled by a different edge cache server:

X-Cache: MISS, HIT
X-Served-By: cache-iad2120-IAD, cache-sjc3122-SJC
X-Cache-Hits: 0, 1

This third request is very similar to the second, but in being handled by a different cache node (cache-sjc3122-SJC) at the edge POP, X-Cache-Hits reflects the hit count at the individual server level so still shows only 1 hit on this machine and 0 at the shield POP.

Choosing a shield location

You should choose a shield POP that is physically close to your origin servers. There are a few other parameters that can be taken into account too:

• Some Fastly POPs have interconnection points with cloud provider networks. Where a POP has a private network interconnect (PNI), requests from that POP to any host that is within that provider's network will typically flow over the interconnect and not via the public internet. If your origin is hosted with one of these providers, choose a shield location where we have an interconnect for optimal performance and potential cost savings.
• Fastly POPs vary dramatically in size and current spare capacity. Choose a POP that offers the largest cache storage for a better cache hit ratio at the shield, and therefore reduced origin traffic.

Understanding PNI cost savings

Depending on your origin's provider, choosing a shield location with an interconnect could provide significant cost savings.

Shield locations

The following POPs are suitable for shielding Fastly services:

Cloud provider recommendations are powered by jsDelivr's Globalping platform. jsDelivr is a member of our community program, which nurtures and supports projects that share our vision of an open internet that is fast and secure for all.

This is not a complete list of Fastly POPs. For a complete list, see the POPs API, run fastly pops on your terminal, or see our network map.