Variables in VCL
VCL provides a multitude of predefined variables describing the state and properties of a request, and also provides a mechanism for declaring custom local variables. Custom variables are always scoped to the subroutine in which they are defined, while predefined variables have a variety of different scopes depending on their purpose and content, and their availability is indicated on each variable's reference page.
Predefined variables
Explore all available variables here:
- Backend connection
- Backend request
- Backend response
- Cache object
- Client connection
- Client request
- Client response
- Date and time
- ESI
- Geolocation
- Math constants limits
- Miscellaneous
- Rate limiting
- Segmented caching
- Server
- Waf
Several predefined variables relate to various views of the HTTP exchange: the client request (req), backend request (bereq), backend response (beresp), cached object (obj), and client response (resp). These are accessible in their respective parts of the VCL lifecycle (for [R]eading and [W]riting):
| Variable | recv | hash | hit | miss | pass | fetch | error | deliver | log |
|---|---|---|---|---|---|---|---|---|---|
| req.* | R/W | R/W | R/W | R/W | R/W | R/W | R/W | R/W | R/W |
| bereq.* | R/W | R/W | R/W | R 1️⃣ | |||||
| obj.* | R | R/W | |||||||
| beresp.* | R/W | ||||||||
| resp.* | R/W | R/W |
1️⃣ A small number of bereq. variables are available to read in the vcl_log subroutine.
User defined variables
Custom variables must be declared before they are used, usually at the beginning of a subroutine, before any statements. They can only be used in the same subroutine in which they are declared. Fastly VCL does not provide block scope: declarations apply to an entire subroutine's scope even if a variable is declared within a block.
Custom variables must start with var. and otherwise consist of characters in the set [A-Za-z0-9._-]. The declaration syntax is:
declare local var.{NAME} {TYPE};For example:
declare local var.gcs_bucket_name STRING;Variables can be any of the valid VCL types. Declared variables are initialized to the zero value of the type:
You can assign values to custom variables using set (custom variables cannot be unset):
set var.gcs_bucket_name = "production-site";