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

VCL snippets are short blocks of VCL logic that can be included directly in your service configurations. They're ideal for adding small sections of code when you don't need more complex, specialized configurations that sometimes require custom VCL. Fastly supports two types of VCL snippets: regular and dynamic.

Regular VCL snippets

Regular VCL snippets belong to a specific service, making them versioned objects. Any modifications you make to the snippet are locked and deployed each time you deploy a new version of that service. Changes to regular snippets will only take effect when you activate your current service version. We continue to clone them and deploy them with a service until you specifically delete them.

Example use: location-based redirection. Say that you work at a large content publisher and you want to redirect users to different editions of your publication depending on which country their request comes from. Say also that you want the ability to override the edition you deliver to them based on a cookie.

Using regular VCL snippets, you could add a new object with the relevant VCL as follows:

if (req.http.Cookie:edition == "US" || client.geo.country_code == "US") {
  set req.http.Edition = "US";
  set req.backend = F_US;
} elseif (req.http.Cookie:edition == "Europe" || server.region ~ "^EU-" ) {
  set req.http.Edition = "EU";
  set req.backend = F_European;
} else {
  set req.http.Edition = "INT";
  set req.backend = F_International;
}

This would create an Edition header in VCL, but allow you to override it by setting a condition. You would add the Edition header into Vary and then add a false condition (e.g., !reg.url) to your other backends to ensure the correct edition of your publication gets delivered. (Remember: VCL snippets get added to VCL before backends are set.)

Dynamic VCL snippets

Dynamic VCL snippets do not belong to a specific service and can be modified independently from other service changes, making them versionless objects (much like dictionaries or ACLs). Though you need to activate your service version once when first creating a dynamic snippet, subsequent changes to the snippet code will be applied immediately, without requiring service activation. This means that, once you've created a snippet for the first time and deployed it to your active service, you can modify the snippet's code any time thereafter without deploying a service version that may not be ready for production. Changes to your snippet's code will immediately impact all service versions, including the active one.

Example use: blocking site scrapers. Say you wanted to implement some pattern matching against incoming requests to block someone trying to scrape your site. Say also that you've developed a system that looks at all incoming requests and generates a set of rules that can identify scrapers using a combination of the incoming IP address, the browser, and the URL they're trying to fetch. Finally, say that the system updates the rules every 20 minutes.

If, during system updates, your colleagues are also making changes to the rest of your Fastly configuration, you probably don't want the system to automatically deploy the latest version of the service since it might be untested. Instead you could generate the site scraper blocking rules as a Dynamic VCL snippet. That way, anytime the snippet is updated after its initial creation, all other logic would remain the same as the currently deployed version and only your blocking rules would be modified.

Limitations of VCL snippets

• Snippets are limited to 1MB in size by default. If you need to store snippets larger than the limit, contact support.
• Snippets don’t support conditions created through the Fastly control panel. You can, however, use if statements in snippet code.
• Snippets cannot be shared between services.
• Snippets cannot be nested. You can't include a snippet into another snippet.

Related content

• About Fastly VCL
• Using VCL
• VCL snippets API documentation