--- title: Backend summary: null url: https://www.fastly.com/documentation/reference/vcl/declarations/backend --- A `backend` declaration creates an origin server in VCL code. This can also be achieved via an [API call](https://www.fastly.com/documentation/reference/api/services/backend/#create-backend), [using the CLI](https://www.fastly.com/documentation/reference/cli/backend/create/), or using the [web interface](https://www.fastly.com/documentation/guides/getting-started/services/about-services). For more information about using backends, see our [guide to integrating with backend servers](https://www.fastly.com/documentation/guides/integrations/non-fastly-services/developer-guide-backends). > **TIP:** 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](https://www.fastly.com/documentation/guides/concepts/shielding/). [Learn more](https://www.fastly.com/documentation/guides/integrations/non-fastly-services/developer-guide-backends). ## Syntax The following examples show the syntax of a backend definition in VCL with various properties: ```vcl 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; .fetch_timeout = 120s; .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](https://www.fastly.com/documentation/reference/api/services/backend/), with the following exceptions: | VCL `backend` property | API equivalent | Note | | --------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `.dynamic` | _None_ | Must be set to `true` in VCL | | `.share_key` | _None_ | Allows health checks to be consolidated \[[Learn more](https://www.fastly.com/documentation/reference/vcl/declarations/backend#using-share_key-to-reduce-health-check-load)] | | `.host` | `address`, `hostname`, `ipv4` and `ipv6` | | | `.ssl` | `use_ssl` | | | `.between_bytes_timeout` | `between_bytes_timeout` | See [specifying durations](https://www.fastly.com/documentation/reference/vcl/declarations/backend#specifying-durations) | | `.connect_timeout` | `connect_timeout` | See [specifying durations](https://www.fastly.com/documentation/reference/vcl/declarations/backend#specifying-durations) | | `.first_byte_timeout` | `first_byte_timeout` | See [specifying durations](https://www.fastly.com/documentation/reference/vcl/declarations/backend#specifying-durations) | | `.fetch_timeout` | `fetch_timeout` | See [specifying durations](https://www.fastly.com/documentation/reference/vcl/declarations/backend#specifying-durations) | | `.bypass_local_route_table` | _None_ | See [bypassing local routing](https://www.fastly.com/documentation/reference/vcl/declarations/backend#bypassing-local-routing) | \| `.probe` \| [Health check API](https://www.fastly.com/documentation/reference/api/services/healthcheck/) | In the API, health checks are created independently of backends. [Learn more about health checks](https://www.fastly.com/documentation/guides/concepts/healthcheck/). | ## Backend hostname requirements VCL backend definitions include several fields that can specify a hostname: - `.host` - `.ssl_hostname` - `.ssl_cert_hostname` - `.ssl_sni_hostname` ### RFC guidelines Hostnames are validated according to the following RFC guidelines: - **[RFC 952](https://tools.ietf.org/html/rfc952) Name**: A name is composed of alphabet (A-Z), digits (0-9), minus sign (-), and period (.). The periods are only used as delimiters for the components of the domain name (i.e., labels). - **[RFC 1123 §2.1](https://tools.ietf.org/html/rfc1123#section-2.1) Host names and numbers**: The first letter of a host name may be either a letter or a digit. It should be possible to enter either a host domain name or an IP address in dotted-decimal (`#.#.#.#`) form. - **[RFC 1035 §2.3.4](https://tools.ietf.org/html/rfc1035#section-2.3.4) Size limits**: Labels (delimited by the '.' character) must be 63 octets or fewer and domain names must be 255 octets or fewer. - **[RFC 1034 §3.1](https://tools.ietf.org/html/rfc1034#section-3.1) Name space specifications and terminology**: A zero-length label is reserved for root. Since all domain names end at the root, they are permitted to add a trailing '.' to terminate the name. - **[RFC 3696 §2](https://tools.ietf.org/html/rfc1034#section-2) Restrictions on domain (DNS) names**: Top-level domain names cannot be all numeric (e.g., `www.example.123`). ### Fastly-specific concessions - Fastly allows the use of the underscore character in the hostname because of its acceptance by popular browsers and its historical use in web hosting services. - Fastly allows the use of a wildcard in the `.ssl_hostname`, `.ssl_cert_hostname`, and `.ssl_sni_hostname` fields. ## Specifying durations Durations of time in VCL backend properties are expressed using `RTIME` literals, while the API takes a number in milliseconds. ## Backend healthcheck probes Healthcheck probes monitor DNS changes and the "health state" of the backend for which the probe was defined. Probe healthcheck requests sent from the Fastly client contain the User-Agent "Varnish/2.1+fastly (healthcheck)". If the `.ssl` field value is set to `true` on the backend, the probe request for the backend is transmitted over TLS. Healthcheck probes have the following properties: | Field | Description | | :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `.dummy` | A boolean flag that controls probe behavior. When set to `true`, the probe only performs DNS resolution of the host if it is a dynamic hostname. When set to `false`, the probe will perform DNS resolution of the dynamic hostname, as well as transmit periodic HTTP requests to the backend. If not set, defaults to `false`. | | `.request` | The HTTP request string for the probe. This property is mutually exclusive with `.url`. If not set, then `.url` is used for the probe request. | | `.url` | The relative URL path to send the probe. An HTTP `GET` request is constructed from `.url` and the backend's `host_header` field value - if defined - otherwise the backend's `host` field value. This property is mutually exclusive with the `.request` field. If not set, defaults to `/`. | | `.expected_response` | The expected HTTP status code that qualifies as a "healthy status" from the backend. Must be between `100` and `999`. If not set, defaults to `200`. | | `.timeout` | The timeout to apply to the probe request. Must be a non-negative value followed by a time unit (`ms`, `s`, or `m`) and must fall between `500ms` and `5m`. If timeout is `\<500ms`, it is updated to `500ms`. This value is also used to timeout DNS queries. If not set or set to `0`, defaults to `2s`. | | `.interval` | The interval at which probe requests are sent to the backend. Must be `0.5s` or greater. If not set, defaults to `5s`. | | `.threshold` | The number of probe requests within the specified `.window` that must succeed in order to determine the backend as "healthy". Must be 64 or less. If `.threshold` is defined, then `.window` must also be defined. Must be less than or equal to the `.window` field value. If not set, defaults to `3`. | | `.window` | The sliding window of probe requests to evaluate when determining if the backend is "healthy". Must be 64 or less. If `.window` is defined, then `.threshold` must also be defined. Must be greater than or equal to the `.threshold` field value. If not set, defaults to `8`. | | `.initial` | The artificial number of successful probes to evaluate when the VCL is activated. If not set, defaults to one less than the `.threshold` value (or `0` if `.threshold` is set to `0`). | In the following example, a probe request is created for my_backend. When the VCL is activated, two probe requests are considered to have succeeded. Three out of five requests, however, are needed to determine if the backend is "healthy". A probe request to [www.example.com/website-healthcheck.txt](http://www.example.com/website-healthcheck.txt) will be sent every fifteen seconds with a timeout of 5s. If the backend responds with a 200 status code for three out of five requests, the backend will be determined as "healthy." ```vcl backend my_backend { .host = "www.example.com" .probe = { .request = "HEAD /website-healthcheck.txt HTTP/1.1" "Host: www.example.com" "Connection: close"; .interval = 15s; .initial = 2; .threshold = 3; .window = 5; .dummy = false; } } ``` ## 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, the `share_key` property is automatically set to the service ID. This ensures that two backends added to two different services will perform health checks independently, even if they are otherwise identical. However, consolidating health checks for all identical backends is usually a good idea. To do this, 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](https://www.fastly.com/documentation/guides/concepts/healthcheck/) ## 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](https://www.fastly.com/documentation/guides/concepts/shielding) requests (which target a specific POP). This situation normally arises as a result of [service chaining](https://www.fastly.com/documentation/guides/concepts/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 [Fastly support](https://support.fastly.com/) to make a request. ## Usage A backend is assigned to a request by setting the value of `req.backend` in VCL: ```vcl context="sub vcl_recv { ... }" set req.backend = backend_name; ```