Guide to VCL

      Last updated October 17, 2019

    Fastly’s Edge Cloud services use the Fastly Varnish Configuration Language (VCL). Fastly VCL allows you to generate and compile changes to your Fastly services. These changes can be distributed to all Fastly caches worldwide and then loaded and activated without requiring maintenance windows or service downtime. Fastly VCL is generated automatically per your service configurations specified via the web interface.

    VCL and what you can do with it

    We allow you to create your own VCL files with specialized configurations. Your custom VCL files can be uploaded into Fastly caches and activated.

    You can also mix and match custom VCL and Fastly VCL, using them together at the same time. You will never lose the options on the Fastly user interface when you use custom VCL, but keep in mind that custom VCL always takes precedence over any VCL generated by the user interface. Be mindful of where your custom VCL sits in the default VCL.

    Fastly VCL Extensions

    In addition, Fastly has included a number of extensions to VCL that won't be covered by any other documentation. Specifically:

    Extension Description
    accept-language features Provides functions to parse and normalize the Accept-Language header.
    cryptographic and hashing functions Supports Hash-based Message Authentication Code (HMAC), a message authentication code that uses a cryptographic key in conjunction with a hash function.
    date- and time-related features Supports the default VCL "now" variable that provides the current time as an RFC 850 formatted date (e.g., Tuesday, 29-Apr-14 08:41:55), as well as several new functions that allow you to have more flexibility when dealing with dates and times.
    Geolocation features Provides the ability to search a geolocation database for a given host or IP address, and return information about the country, city or Internet Service Provider (ISP) for that IP address.
    local variables in VCL Supports variables for storing temporary values during request processing.
    randomness features Supports the insertion of random strings, content cookies, and decisions into requests.
    size-related variables Supports reporting variables that offer insight into what happened in a request.
    TLS and HTTP/2 variables Supports the use of variables and functions related to TLS and HTTP/2.
    miscellaneous features and variables Provides miscellaneous VCL extensions not easily grouped into other categories.

    Embedding inline C code in VCL

    Currently, we don't provide embedded C access to our users. Fastly is a shared infrastructure. By allowing the use of inline C code, we could potentially give a single user the power to read, write to, or write from everything. As a result, our varnish process (i.e., files on disk, memory of the varnish user's processes) would become unprotected because inline C code opens the potential for users to do things like crash servers, steal data, or run a botnet.

    We appreciate feedback from our customers. If you are interested in a feature that requires C code, contact Our engineering team looks forward to these kinds of challenges.

    Where to learn more about Varnish and VCL

    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.

    Roberto Moutinho's book Instant Varnish Cache also provides information.

    Back to Top