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

Fastly VCL is a domain-specific programming language that evolved from the Varnish proxy cache, forming a core part of Fastly's platform architecture. This scripting language is intentionally limited in scope, allowing it to run extremely fast while maintaining network security and making it available to all requests passing through Fastly. With VCL, you can accomplish everything from simple tasks like adding cookies or setting Cache-Control headers to complex implementations like complete paywall solutions.

Unlike traditional applications, VCL services don't provide a single entry point for your code. Instead, Fastly exposes built-in subroutines as "hooks" that execute at significant moments during each HTTP request's lifecycle. This approach means your uploaded code functions as a configuration rather than a standalone application. Changes to your VCL can be generated automatically through the Fastly control panel, compiled, and distributed to all Fastly caches worldwide, all without requiring maintenance windows or service downtime.

VCL and what you can do with it

You can create custom VCL files with specialized configurations and upload them into Fastly caches for activation. Fastly supports mixing and matching custom VCL with Fastly-generated VCL, using them together simultaneously. While you retain all control panel options when using custom VCL, keep in mind that custom VCL always takes precedence over any VCL generated by the control panel.

The VCL request lifecycle

The following subroutines are triggered by Fastly in this order:

Some subroutines can return error, restart, or upgrade. Any error return state will result in the execution flow passing to vcl_error, while restart will result in the execution flow passing to vcl_recv. The special upgrade return state will terminate the VCL flow and create a managed WebSocket connection (learn more).

Adding VCL to your service configuration

Everything that your VCL service does is powered by VCL. Even features that you enable in the web interface or via the API without writing code yourself will ultimately generate VCL code written by Fastly. To support combining your own VCL logic with Fastly's generated code, we include macros in the VCL program, one in each subroutine, such as #FASTLY recv.

You can mix and match creating configuration using high-level VCL generative objects, VCL snippets, and full custom VCL files, and all are interoperable - though it's typically more maintainable to choose a single approach.

VCL generative objects

Using the web interface or API, you can create configuration objects that generate VCL for you.

VCL snippets

By adding your custom VCL code using snippets, you can insert raw code into VCL subroutines alongside Fastly-generated code. Your code snippets will be added at the end of the subroutine you select, which can have an impact on what is possible with snippets.

Snippets can be regular or dynamic.

• Regular snippets are versioned in the same way as the rest of your service. Changes require a new version of the service configuration, and can therefore also be rolled back with a rollback of the service version. These are a good choice for VCL code that performs logical actions like routing, setting headers, or authentication.
• Dynamic snippets are not versioned. After attaching a dynamic snippet to a version of your service and activating it, any subsequent changes you make to the snippet apply immediately. This also means if you roll back a service configuration to a earlier version, and the snippet was present in that earlier version, the snippet will remain unchanged and contain the latest code. Dynamic snippets are useful for including generated logic or declarative data, such as redirection rules or allowlists (although if you can use a dictionary that's typically a better solution).

If you have VCL snippets defined on a service that also has custom VCL, the snippets will typically be rendered as part of the Fastly macro, replacing the placeholders such as #FASTLY recv that you must include in any custom VCL file. However, if your snippet has a type of "none", you may include the snippet explicitly at any point in your 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 to set bereq.http.cookie you cannot include that snippet in the vcl_recv subroutine, because bereq is not available in the vcl_recv scope. See VCL variables for more details).

Custom VCL

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

We recommend that you start from the following boilerplate, which 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 {
  set req.hash += req.url;
  set req.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) {
    unset beresp.http.Set-Cookie;
    unset beresp.http.Vary;
  }

  # Log the number of restarts for debugging purposes
  if (req.restarts > 0) {
    set beresp.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)") {
    set beresp.ttl = 3600s;

    # Apply a longer default TTL for images processed using Image Optimizer
    if (req.http.X-Fastly-Imageopto-Api) {
      set beresp.ttl = 2592000s; # 30 days
      set beresp.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's Developer Hub provides a reference of Fastly VCL for programming custom edge logic on VCL services. You can also discover more about learning to build on the Fastly platform using VCL and the current best practices involved.

The official Varnish documentation is a good place to start when looking for online information. In addition, Varnish Software, who provides commercial support for Varnish, has written a free online book.

Related content

• VCL API documentation