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";
    .initial = 5;
    .threshold = 1;
    .timeout = 2s;
    .window = 5;
  }
}

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. Healthchecks are already performed independently from each data center, so if you have 10 services and there are 100 data centers and you configure your healthcheck to try your origin once per second, this will create healthcheck traffic of 1000 rps.

If all ten of those services use exactly the same backend with the same settings, and you define the backend in VCL, use an identical share_key, this will consolidate their healthchecks. In the above example this would reduce healthcheck load to only 100 rps.

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;