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.

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;


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

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

  • All backend definitions in VCL must additionally have a dynamic property set to true and a share_key (see below).
  • The API properties address, hostname, ipv4 and ipv6 map to the host property of the backend declaration.
  • The API property use_ssl becomes ssl here.
  • Time values are expressed using RTIME literals here, while the API takes a number in milliseconds.
  • The probe field in the backend declaration is configured via the API separately as a healthcheck.

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

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;