Backend

A backend declaration creates an origin server in VCL code.

This can also be achieved via an API call, using the CLI, or using the web interface.

WARNING: It's usually better to create backends using the API, CLI, or web interface, rather than using custom VCL code. This will offer better validation, and enable a number of features not available to VCL-defined backends, including shielding.

Syntax

The following examples show the syntax of a backend definition with all possible properties:

backend backend_name {
# Required to be set for all VCL defined backends
.dynamic = true;
.share_key = "YOUR_SERVICE_ID";
# Server location
.host = "storage.googleapis.com";
.port = "443";
.ssl = true;
.ssl_cert_hostname = "storage.googleapis.com";
.ssl_check_cert = always;
.ssl_sni_hostname = "storage.googleapis.com";
# Timeouts and limits
.between_bytes_timeout = 10s;
.connect_timeout = 1s;
.first_byte_timeout = 15s;
.max_connections = 200;
# Host header override
.host_header = "storage.googleapis.com";
.always_use_host_header = true;
# Protected properties
.bypass_local_route_table = true;
# Healthcheck
.probe = {
.dummy = true;
.request = "HEAD / HTTP/1.1" "Host: storage.googleapis.com" "Connection: close";
.expected_response = 200;
.interval = 60s; # Send a check every 60s
.timeout = 2s; # Allow up to 2s for the backend to respond to the check
.window = 5; # Keep a history of 5 checks
.initial = 3; # Start with 3 successful checks in the history
.threshold = 4; # 4 of the recent checks must be successful for backend to be healthy
}
}

A backend name is alphanumeric and may not start with a number (most backends created via the API, CLI or web interface will be prefixed with F_ in VCL to prevent a leading digit). Non-alphanumeric characters will be converted to _.

Property descriptions are the same as those described in the API reference, with the following exceptions:

VCL backend propertyAPI equivalentNote
.dynamicNoneMust be set to true in VCL
.share_keyNoneAllows healthchecks to be consolidated [Learn more]
.hostaddress, hostname, ipv4 and ipv6
.ssluse_ssl
.between_bytes_timeoutbetween_bytes_timeoutSee specifying durations
.connect_timeoutconnect_timeoutSee specifying durations
.first_byte_timeoutfirst_byte_timeoutSee specifying durations
.bypass_local_route_tableNoneSee bypassing local routing
.probeHealthcheck APIIn the API, healthchecks are created independently of backends

Specifying durations

Durations of time in VCL backend properties are expressed using RTIME literals, while the API takes a number in milliseconds.

Using share_key to reduce healthcheck load

Backends with identical definitions, including the healthcheck (.probe property in VCL), will share the same healthcheck process. However, since this behavior can be unexpected, backends created via the API, CLI, or web interface will automatically set the share_key property to the service ID. This ensures that two otherwise-identical backends added to two different services will perform healthchecks independently.

Defining backends in VCL, however, provides an opportunity to set the share_key to something that is consistent across multiple services in your account. If the backends are also identical in all other ways, they will share the same healthcheck, reducing the amount of healthcheck traffic to your origin. Learn more about healthchecks

Bypassing local routing

By default, Fastly cache servers will handle any request from a Fastly service to a backend that is also hosted by Fastly by internally routing within the same machine, except for shielding requests (which target a specific POP). This situation normally arises as a result of service chaining. Bypassing local routing will prompt Fastly to resolve any Fastly-hosted backends using public DNS, which may result in the request being handled by a different cache server (and rarely, perhaps even a different POP).

IMPORTANT: Local route bypass is a protected feature which must be explicitly allowed on your service by a Fastly employee before the route bypass setting will take effect. Contact support@fastly.com to make a request.

Usage

A backend is assigned to a request by setting the value of req.backend in VCL:

sub vcl_recv { ... }
Fastly VCL
set req.backend = backend_name;