1. Home
2. Guides
3. Full-Site Delivery
4. Fastly VCL

Fastly VCL is adomain-specific programming language that evolved from theVarnish proxy cache, forming a core part of Fastly's platform architecture. The Varnish Configuration Language (VCL) is intentionally limited in scope so that it can run quickly, maintain strong security, and be applied consistently to every request passing through Fastly.

With VCL you can handle everything from simple tasks like settingCache-Control headers, to building advanced implementations like authentication flows or full paywall systems.

VCL and what you can do with it

Every Fastly service runs on VCL, even when you don't write any code yourself. Each time you configure features in the web interface or via the API, Fastly translates those configuration settings automatically into generated VCL.

You aren't limited to using just generated VCL however. You can mix and match your code with the generated VCL, using them together to create specialized configurations. Your code customizations can modify and extend Fastly's own generated logic. Keep in mind, however, that VCL code you create always takes precedence over any VCL generated by the control panel.

The VCL request lifecycle

VCL does not run like a traditional program with a single entry point for your code. Instead, Fastly exposes built-in subroutines ashooks that execute at significant moments during each HTTP request's lifecycle. These hooks are where you can add your code.

This approach means your uploaded code functions as aconfiguration rather than a standalone application. Changes to your VCL can be generated automatically through theFastly control panel, compiled, and distributed to all Fastly caches worldwide, all without requiring maintenance windows or service downtime.

Here are the main subroutines, in the order they run:

Some subroutines can returnerror,restart, orupgrade. Anyerror return state will result in the execution flow passing tovcl_error, whilerestart will result in the execution flow passing tovcl_recv. The specialupgrade return state will terminate the VCL flow and create a managed WebSocket connection (learn more).

Ways to add VCL code to service configurations

You can add custom behavior to your services in three ways, each of which you can mix and match to create specialized configurations:

• viaVCL generative objects, features you configure using the Fastly control panel's web interface or the API
• viaVCL snippets, short blocks of code you attach to subroutines in generated VCL
• viacustom VCL, a full VCL file that you upload to replace the one Fastly generates

To make all three methods work together, Fastly usesmacros inside each subroutine. Macros (for example,#FASTLY recv) act as placeholders where Fastly inserts generated code and snippets during compilation. If you remove them, Fastly cannot insert its generated logic, and your service may fail to compile.

VCL generative objects

Generative objects let you configure behavior without writing code. Fastly turns them into VCL automatically.

VCL snippets

VCL snippets are short blocks of VCL logic that extend or modify the default Fastly-generated configuration. They are most useful when you want to make targeted changes to your service's settings because they don't require you to replace the generated VCL.

Snippets come in two types:

• Regular snippets: used for procedural logic such as setting headers, routing requests, or applying access controls.
• Dynamic snippets: used for inserting generated rules or structured data such as redirects or allowlists. (If possible, use adictionary instead, since it is easier to manage.)

If you have VCL snippets defined on a service that also has custom VCL, the snippets will typically be rendered inside of the Fastly macros, replacing the placeholders that you must include in any custom VCL file.

Snippets can be included as many times and in as many places as desired, subject to compiler rules. For example, if your snippet attempts toset bereq.http.cookie you cannot include that snippet in thevcl_recv subroutine, becausebereq is not available in thevcl_recv scope. Our guide toVCL variables contains more details.

Custom VCL

Custom VCL allows you to upload a full VCL source file to entirely replace the one that would otherwise be generated by Fastly. To make sure that features you create usingVCL generative objects still work, we require that custom VCL files include Fastly's macros, one in each subroutine.

We recommend starting your custom VCL file with Fastly's boilerplate. It includes all the required Fastly macro placeholders and also presents VCL subroutines in the order in which they are executed.

sub vcl_recv {
#FASTLY recv
# Normally, you should consider requests other than GET and HEAD to be uncacheable
# (to this we add the special FASTLYPURGE method)
if (req.method!="HEAD"&&req.method!="GET"&&req.method!="FASTLYPURGE") {
return(pass);
  }
# If you are using image optimization, insert the code to enable it here
# See https://www.fastly.com/documentation/reference/io/ for more information.
return(lookup);
}
sub vcl_hash {
setreq.hash+=req.url;
setreq.hash+=req.http.host;
#FASTLY hash
return(hash);
}
sub vcl_hit {
#FASTLY hit
return(deliver);
}
sub vcl_miss {
#FASTLY miss
return(fetch);
}
sub vcl_pass {
#FASTLY pass
return(pass);
}
sub vcl_fetch {
#FASTLY fetch
# Unset headers that reduce cacheability for images processed using the Fastly image optimizer
if (req.http.X-Fastly-Imageopto-Api) {
    unsetberesp.http.Set-Cookie;
    unsetberesp.http.Vary;
  }
# Log the number of restarts for debugging purposes
if (req.restarts>0) {
setberesp.http.Fastly-Restarts=req.restarts;
  }
# If the response is setting a cookie, make sure it is not cached
if (beresp.http.Set-Cookie) {
return(pass);
  }
# By default we set a TTL based on the `Cache-Control` header but we don't parse additional directives
# like `private` and `no-store`. Private in particular should be respected at the edge:
if (beresp.http.Cache-Control~"(?:private|no-store)") {
return(pass);
  }
# If no TTL has been provided in the response headers, set a default
if (!beresp.http.Expires&&!beresp.http.Surrogate-Control~"max-age"&&!beresp.http.Cache-Control~"(?:s-maxage|max-age)") {
setberesp.ttl=3600s;
# Apply a longer default TTL for images processed using Image Optimizer
if (req.http.X-Fastly-Imageopto-Api) {
setberesp.ttl=2592000s;# 30 days
setberesp.http.Cache-Control="max-age=2592000, public";
    }
  }
return(deliver);
}
sub vcl_error {
#FASTLY error
return(deliver);
}
sub vcl_deliver {
#FASTLY deliver
return(deliver);
}
sub vcl_log {
#FASTLY log
}

Constraints and limitations

VCL services are subject to the following restrictions or limits:

Where to learn more about VCL and Varnish

Fastly provides a VCLreference for programming custom logic on VCL services along with guides onusing VCL and the currentbest practices. These resources focus on how VCL works within the Fastly platform.

For background information on the language itself, theofficial Varnish documentation is a good online starting point. Varnish Software, which provides commercial support for Varnish, also maintains afree online book covering more technical details.

Related content

• VCL API documentation