1. Home
2. Reference documentation
3. VCL Reference
4. Declarations

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. For more information about using backends, see our guide to integrating with backend servers.

Syntax

The following examples show the syntax of a backend definition in VCL 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;

  # Health check
  .probe = {
    .dummy = false; # Boolean value determines the behavior of the probe.
                    # `true` performs DNS lookups only.
                    # `false` performs DNS lookups and HTTP health checks.
    .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 = 4;      # Start with 4 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:

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 health check load

Backends with identical definitions, including the health check (.probe property in VCL), will share the same health check 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 health checks 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 health check, reducing the amount of health check traffic to your origin. Learn more about health checks

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).

Usage

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

set req.backend = backend_name;