Provided by: varnish_3.0.2-1_amd64 bug

NAME

       VCL - Varnish Configuration Language

DESCRIPTION

       The VCL language is a small domain-specific language designed to be used to define request
       handling and document caching policies for Varnish Cache.

       When a new configuration is loaded, the varnishd management  process  translates  the  VCL
       code  to  C  and  compiles it to a shared object which is then dynamically linked into the
       server process.

SYNTAX

       The VCL syntax is very simple, and  deliberately  similar  to  C  and  Perl.   Blocks  are
       delimited  by curly braces, statements end with semicolons, and comments may be written as
       in C, C++ or Perl according to your own preferences.

       In addition to the C-like assignment (=), comparison (==, !=) and boolean (!, &&  and  ||)
       operators,  VCL  supports  both regular expression and ACL matching using the ~ and the !~
       operators.

       Basic strings are enclosed in " ... ", and may not contain newlines.

       Long strings are enclosed in {" ... "}.  They  may  contain  any  character  including  ",
       newline and other control characters except for the NUL (0x00) character.

       Unlike C and Perl, the backslash () character has no special meaning in strings in VCL, so
       it can be freely used in regular expressions without doubling.

       Strings are concatenated using the '+' operator.

       Assignments are introduced with the set keyword.  There  are  no  user-defined  variables;
       values can only be assigned to variables attached to backend, request or document objects.
       Most of these are typed, and the values assigned to  them  must  have  a  compatible  unit
       suffix.

       You  can  use  the  set keyword to arbitrary HTTP headers. You can remove headers with the
       remove or unset keywords, which are synonym.

       You can use the rollback keyword to revert any changes to req at any time.

       The synthetic keyword is used to produce a synthetic response body in vcl_error. It  takes
       a single string as argument.

       You  can force a crash of the client process with the panic keyword.  panic takes a string
       as argument.

       The return(action) keyword terminates the subroutine. action can be, depending on  context
       one of

       · deliver

       · error

       · fetch

       · hash

       · hit_for_pass

       · lookup

       · ok

       · pass

       · pipe

       · restart

       Please see the list of subroutines to see what return actions are available where.

       VCL has if tests, but no loops.

       The  contents  of  another  VCL file may be inserted at any point in the code by using the
       include keyword followed by the name of the other file as a quoted string.

   Backend declarations
       A backend declaration creates and initializes a named backend object::

       backend www {
         .host = "www.example.com";
         .port = "http";
       }

       The backend object can later be used to select a backend at request time::

       if (req.http.host ~ "(?i)^(www.)?example.com$") {
         set req.backend = www;
       }

       To avoid overloading backend servers, .max_connections can be set  to  limit  the  maximum
       number of concurrent backend connections.

       The  timeout  parameters  can  be  overridden  in  the  backend  declaration.  The timeout
       parameters  are  .connect_timeout  for  the  time  to  wait  for  a  backend   connection,
       .first_byte_timeout  for  the  time  to  wait  for  the  first  byte  from the backend and
       .between_bytes_timeout for time to wait between each received byte.

       These can be set in the declaration like this::

       backend www {
         .host = "www.example.com";
         .port = "http";
         .connect_timeout = 1s;
         .first_byte_timeout = 5s;
         .between_bytes_timeout = 2s;
       }

       To mark a backend as unhealthy after number of items have been added to its saintmode list
       .saintmode_threshold  can  be  set to the maximum list size. Setting a value of 0 disables
       saint mode checking entirely for that backend.   The  value  in  the  backend  declaration
       overrides the parameter.

   Directors
       A  director  is  a logical group of backend servers clustered together for redundancy. The
       basic role of the director is to let Varnish choose a backend server amongst several so if
       one is down another can be used.

       There  are  several  types  of  directors.  The  different  director  types  use different
       algorithms to choose which backend to use.

       Configuring a director may look like this::

       director b2 random {
         .retries = 5;
         {
           // We can refer to named backends
           .backend = b1;
           .weight  = 7;
         }
         {
           // Or define them inline
           .backend  = {
             .host = "fs2";
           }
         .weight         = 3;
         }
       }

   The family of random directors
       There are three directors that share the same logic, called the  random  director,  client
       director and hash director. They each distribute traffic among the backends assigned to it
       using a random distribution seeded with either the client identity, a random number or the
       cache hash (typically url). Beyond the initial seed, they act the same.

       Each  backend requires a .weight option which sets the amount of traffic each backend will
       get compared to the others. Equal weight means equal traffic. A backend with lower  weight
       than an other will get proportionally less traffic.

       The  director has an optional .retries option which defaults to the number of backends the
       director has. The director will attempt .retries times to find a healthy  backend  if  the
       first  attempt  fails.  Each attempt re-uses the previous seed in an iterative manner. For
       the random director this detail is of no importance as it will give different results each
       time.  For  the  hash and client director, this means the same URL or the same client will
       fail to the same server consistently.

   The random director
       This uses a random number to seed the backend selection.

   The client director
       The client director picks a backend based on the clients identity. You  can  set  the  VCL
       variable  client.identity  to  identify  the  client  by picking up the value of a session
       cookie or similar.

   The hash director
       The hash director will pick a backend based on the URL hash value.

       This is useful is you are using Varnish to load balance in front of other  Varnish  caches
       or other web accelerators as objects won't be duplicated across caches.

       It will use the value of req.hash, just as the normal cache-lookup methods.

   The round-robin director
       The round-robin director does not take any options.

       It  will  use  the  first backend for the first request, the second backend for the second
       request and so on, and start from the top again when it gets to the end.

       If a backend is  unhealthy  or  Varnish  fails  to  connect,  it  will  be  skipped.   The
       round-robin director will try all the backends once before giving up.

   The DNS director
       The  DNS  director  can  use  backends  in  two  different ways. Either like the random or
       round-robin director or using .list:

       director directorname dns {
               .list = {
                       .host_header = "www.example.com";
                       .port = "80";
                       .connect_timeout = 0.4s;
                       "192.168.15.0"/24;
                       "192.168.16.128"/25;
               }
               .ttl = 5m;
               .suffix = "internal.example.net";
       }

       This will specify 384 backends, all using port  80  and  a  connection  timeout  of  0.4s.
       Options  must  come  before the list of IPs in the .list statement.  The .list-method does
       not support IPv6. It is not a white-list, it is an actual list of backends  that  will  be
       created internally in Varnish - the larger subnet the more overhead.

       The .ttl defines the cache duration of the DNS lookups.

       The  above example will append "internal.example.net" to the incoming Host header supplied
       by the client, before looking it up. All settings are optional.

       Health checks are not thoroughly supported.

       DNS round robin balancing is supported. If a hostname resolves to multiple  backends,  the
       director will divide the traffic between all of them in a round-robin manner.

   The fallback director
       The  fallback  director  will pick the first backend that is healthy. It considers them in
       the order in which they are listed in its definition.

       The fallback director does not take any options.

       An example of a fallback director:

       director b3 fallback {
         { .backend = www1; }
         { .backend = www2; } // will only be used if www1 is unhealthy.
         { .backend = www3; } // will only be used if both www1 and www2
                              // are unhealthy.
       }

   Backend probes
       Backends can be probed to see whether they should  be  considered  healthy  or  not.   The
       return status can also be checked by using req.backend.healthy.

       Probes take the following parameters:

       .url   Specify a URL to request from the backend.  Defaults to "/".

       .request
              Specify  a  full  HTTP  request  using  multiple  strings.  .request will have \r\n
              automatically inserted after  every  string.   If  specified,  .request  will  take
              precedence over .url.

       .window
              How  many  of the latest polls we examine to determine backend health.  Defaults to
              8.

       .threshold
              How many of the polls in .window must have succeeded for us to consider the backend
              healthy.  Defaults to 3.

       .initial
              How  many  of  the probes are considered good when Varnish starts.  Defaults to the
              same amount as the threshold.

       .expected_response
              The expected backend HTTP response code.  Defaults to 200.

       .interval
              Defines how often the probe should check the backend.  Default is every 5 seconds.

       .timeout
              How fast each probe times out.  Default is 2 seconds.

       A backend with a probe can be defined like this, together with the backend or director::

       backend www {
         .host = "www.example.com";
         .port = "http";
         .probe = {
           .url = "/test.jpg";
           .timeout = 0.3 s;
           .window = 8;
           .threshold = 3;
           .initial = 3;
         }
       }

       Or it can be defined separately and then referenced::

       probe healthcheck {
          .url = "/status.cgi";
          .interval = 60s;
          .timeout = 0.3 s;
          .window = 8;
          .threshold = 3;
          .initial = 3;
          .expected_response = 200;
       }

       backend www {
         .host = "www.example.com";
         .port = "http";
         .probe = healthcheck;
       }

       If you have many backends this can simplify the config a lot.

       It is also possible to specify the raw HTTP request:

       probe rawprobe {
           # NB: \r\n automatically inserted after each string!
           .request =
             "GET / HTTP/1.1"
             "Host: www.foo.bar"
             "Connection: close";
       }

   ACLs
       An ACL declaration creates and initializes a named access control list which can later  be
       used to match client addresses::

       acl local {
         "localhost";         // myself
         "192.0.2.0"/24;      // and everyone on the local network
         ! "192.0.2.23";      // except for the dialin router
       }

       If  an  ACL  entry specifies a host name which Varnish is unable to resolve, it will match
       any address it is com‐ pared to.  Consequently, if it is preceded by a negation  mark,  it
       will  reject  any  address  it is compared to, which may not be what you intended.  If the
       entry is enclosed in parentheses, however, it will simply be ignored.

       To match an IP address against an ACL, simply use the match operator::

       if (client.ip ~ local) {
         return (pipe);
       }

   Regular Expressions
       In Varnish 2.1.0 Varnish switched to using PCRE - Perl-compatible regular expressions. For
       a complete description of PCRE please see the PCRE(3) man page.

       To  send  flags  to  the  PCRE  engine, such as to turn on case insensitivity add the flag
       within parens following a question mark, like this::

       if (req.http.host ~ "(?i)example.com$") {
               ...
       }

   Functions
       The following built-in functions are available:

       hash_data(str)
              Adds a string to the hash input. In default.vcl hash_data() is called on  the  host
              and URL of the request.

       regsub(str, regex, sub)
              Returns  a  copy  of  str with the first occurrence of the regular expression regex
              replaced with sub. Within sub, 0 (which can also be spelled &) is replaced with the
              entire  matched  string,  and  n is replaced with the contents of subgroup n in the
              matched string.

       regsuball(str, regex, sub)
              As regsuball() but this replaces all occurrences.

       ban(ban expression)

       ban_url(regex)
              Bans all objects in cache whose URLs match regex.

   Subroutines
       A subroutine is used to group code for legibility or reusability::

       sub pipe_if_local {
         if (client.ip ~ local) {
           return (pipe);
         }
       }

       Subroutines in VCL do not take arguments, nor do they return values.

       To call a subroutine, use the call keyword followed by the subroutine's name:

       call pipe_if_local;

       There are a number of special subroutines which hook into  the  Varnish  workflow.   These
       subroutines  may  inspect  and  manipulate  HTTP headers and various other aspects of each
       request, and to a  certain  extent  decide  how  the  request  should  be  handled.   Each
       subroutine  terminates  by  calling  one of a small number of keywords which indicates the
       desired outcome.

       vcl_init
              Called when VCL is loaded, before any requests pass through it.  Typically used  to
              initialize VMODs.

              return() values:

              ok     Normal return, VCL continues loading.

       vcl_recv
              Called  at the beginning of a request, after the complete request has been received
              and parsed.  Its purpose is to decide whether or not to serve the request,  how  to
              do it, and, if applicable, which backend to use.

              The vcl_recv subroutine may terminate with calling return() on one of the following
              keywords:

              error code [reason]
                     Return the specified error code to the client and abandon the request.

              pass   Switch to pass mode.  Control will eventually pass to vcl_pass.

              pipe   Switch to pipe mode.  Control will eventually pass to vcl_pipe.

              lookup Look up the requested object in the cache.  Control will eventually pass  to
                     vcl_hit or vcl_miss, depending on whether the object is in the cache.

       vcl_pipe
              Called  upon  entering  pipe  mode.   In this mode, the request is passed on to the
              backend, and any further data from either client or backend is passed on  unaltered
              until either end closes the connection.

              The  vcl_pipe  subroutine  may  terminate  with  calling  return()  with one of the
              following keywords:

              error code [reason]
                     Return the specified error code to the client and abandon the request.

              pipe   Proceed with pipe mode.

       vcl_pass
              Called upon entering pass mode.  In this mode, the request  is  passed  on  to  the
              backend,  and the backend's response is passed on to the client, but is not entered
              into the cache.  Subsequent requests sub‐ mitted over the  same  client  connection
              are handled normally.

              The  vcl_recv  subroutine  may  terminate  with  calling  return()  with one of the
              following keywords:

              error code [reason]
                     Return the specified error code to the client and abandon the request.

              pass   Proceed with pass mode.

              restart
                     Restart the transaction. Increases the restart counter.  If  the  number  of
                     restarts is higher than max_restarts varnish emits a guru meditation error.

       vcl_hash
              You may call hash_data() on the data you would like to add to the hash.

              The  vcl_hash  subroutine  may  terminate  with  calling  return()  with one of the
              following keywords:

              hash   Proceed.

       vcl_hit
              Called after a cache lookup if the requested document was found in the cache.

              The vcl_hit subroutine  may  terminate  with  calling  return()  with  one  of  the
              following keywords:

              deliver
                     Deliver  the  cached  object to the client.  Control will eventually pass to
                     vcl_deliver.

              error code [reason]
                     Return the specified error code to the client and abandon the request.

              pass   Switch to pass mode.  Control will eventually pass to vcl_pass.

              restart
                     Restart the transaction. Increases the restart counter.  If  the  number  of
                     restarts is higher than max_restarts varnish emits a guru meditation error.

       vcl_miss
              Called  after  a cache lookup if the requested document was not found in the cache.
              Its purpose is to decide whether or not to attempt to retrieve  the  document  from
              the backend, and which backend to use.

              The  vcl_miss  subroutine  may  terminate  with  calling  return()  with one of the
              following keywords:

              error code [reason]
                     Return the specified error code to the client and abandon the request.

              pass   Switch to pass mode.  Control will eventually pass to vcl_pass.

              fetch  Retrieve the requested object from the  backend.   Control  will  eventually
                     pass to vcl_fetch.

       vcl_fetch
              Called after a document has been successfully retrieved from the backend.

              The  vcl_fetch  subroutine  may  terminate  with  calling  return() with one of the
              following keywords:

              deliver
                     Possibly insert the object into the cache, then deliver it  to  the  client.
                     Control will eventually pass to vcl_deliver.

              error code [reason]
                     Return the specified error code to the client and abandon the request.

              hit_for_pass
                     Pass in fetch. This will create a hit_for_pass object. Note that the TTL for
                     the hit_for_pass object will be set to what the current value of beresp.ttl.
                     Control  will  be  handled  to  vcl_deliver  on  the  current  request,  but
                     subsequent requests will go directly to vcl_pass based on  the  hit_for_pass
                     object.

              restart
                     Restart  the  transaction.  Increases  the restart counter. If the number of
                     restarts is higher than max_restarts varnish emits a guru meditation error.

       vcl_deliver
              Called before a cached object is delivered to the client.

              The vcl_deliver subroutine may terminate with one of the following keywords:

              deliver
                     Deliver the object to the client.

              error code [reason]
                     Return the specified error code to the client and abandon the request.

              restart
                     Restart the transaction. Increases the restart counter.  If  the  number  of
                     restarts is higher than max_restarts varnish emits a guru meditation error.

       vcl_error
              Called  when  we  hit  an  error, either explicitly or implicitly due to backend or
              internal errors.

              The vcl_error subroutine may terminate by calling return with one of the  following
              keywords:

              deliver
                     Deliver the error object to the client.

              restart
                     Restart  the  transaction.  Increases  the restart counter. If the number of
                     restarts is higher than max_restarts varnish emits a guru meditation error.

       vcl_fini
              Called when VCL  is  discarded  only  after  all  requests  have  exited  the  VCL.
              Typically used to clean up VMODs.

              return() values:

              ok     Normal return, VCL will be discarded.

       If  one  of  these subroutines is left undefined or terminates without reaching a handling
       decision, control will be handed over to the builtin default.  See  the  EXAMPLES  section
       for a listing of the default code.

   Multiple subroutines
       If multiple subroutines with the same name are defined, they are concatenated in the order
       in which the appear in the source.

       Example::

       # in file "main.vcl"
       include "backends.vcl";
       include "ban.vcl";

       # in file "backends.vcl"
       sub vcl_recv {
         if (req.http.host ~ "(?i)example.com") {
           set req.backend = foo;
         } elsif (req.http.host ~ "(?i)example.org") {
           set req.backend = bar;
         }
       }

       # in file "ban.vcl"
       sub vcl_recv {
         if (client.ip ~ admin_network) {
           if (req.http.Cache-Control ~ "no-cache") {
             ban_url(req.url);
           }
         }
       }

       The builtin default subroutines are implicitly appended in this way.

   Variables
       Although subroutines take no arguments, the necessary information is made available to the
       handler subroutines through global variables.

       The following variables are always available:

       now    The current time, in seconds since the epoch.

       The following variables are available in backend declarations:

       .host  Host name or IP address of a backend.

       .port  Service name or port number of a backend.

       The following variables are available while processing a request:

       client.ip
              The client's IP address.

       client.identity
              Identification of the client, used to load balance in the client director.

       server.hostname
              The host name of the server.

       server.identity
              The identity of the server, as set by the -i parameter.  If the -i parameter is not
              passed to varnishd, server.identity will be set to the name  of  the  instance,  as
              specified by the -n parameter.

       server.ip
              The IP address of the socket on which the client connection was received.

       server.port
              The port number of the socket on which the client connection was received.

       req.request
              The request type (e.g. "GET", "HEAD").

       req.url
              The requested URL.

       req.proto
              The HTTP protocol version used by the client.

       req.backend
              The backend to use to service the request.

       req.backend.healthy
              Whether  the  backend  is healthy or not. Requires an active probe to be set on the
              backend.

       req.http.header
              The corresponding HTTP header.

       req.hash_always_miss
              Force a cache miss for this request. If set to  true  Varnish  will  disregard  any
              existing objects and always (re)fetch from the backend.

       req.hash_ignore_busy
              Ignore  any  busy object during cache lookup. You would want to do this if you have
              two server looking up content from each other to avoid potential deadlocks.

       req.can_gzip
              Does the client accept the gzip transfer encoding.

       req.restarts
              A count of how many times this request has been restarted.

       req.esi
              Boolean. Set to false  to  disable  ESI  processing  regardless  of  any  value  in
              beresp.do_esi.  Defaults  to  true.  This  variable  is subject to change in future
              versions, you should avoid using it.

       req.esi_level
              A count of how many levels of ESI requests we're currently at.

       req.grace
              Set to a period to enable grace.

       req.xid
              Unique ID of this request.

       The following variables are available while preparing a  backend  request  (either  for  a
       cache miss or for pass or pipe mode):

       bereq.request
              The request type (e.g. "GET", "HEAD").

       bereq.url
              The requested URL.

       bereq.proto
              The HTTP protocol version used to talk to the server.

       bereq.http.header
              The corresponding HTTP header.

       bereq.connect_timeout
              The time in seconds to wait for a backend connection.

       bereq.first_byte_timeout
              The  time in seconds to wait for the first byte from the backend.  Not available in
              pipe mode.

       bereq.between_bytes_timeout
              The time in seconds to wait between each  received  byte  from  the  backend.   Not
              available in pipe mode.

       The  following  variables are available after the requested object has been retrieved from
       the backend, before it is entered into the cache. In other words, they  are  available  in
       vcl_fetch:

       beresp.do_stream
              Deliver  the  object  to the client directly without fetching the whole object into
              varnish. If this request is pass'ed it will not be stored in memory. As of  Varnish
              Cache  3.0  the  object  will  marked as busy as it is delivered so only client can
              access the object.

       beresp.do_esi
              Boolean. ESI-process the object after fetching it. Defaults to  false.  Set  it  to
              true  to  parse  the  object for ESI directives. Will only be honored if req.esi is
              true.

       beresp.do_gzip
              Boolean. Gzip the object before storing it. Defaults to false.

       beresp.do_gunzip
              Boolean. Unzip the object before storing it in the cache.  Defaults to false.

       beresp.proto
              The HTTP protocol version used the backend replied with.

       beresp.status
              The HTTP status code returned by the server.

       beresp.response
              The HTTP status message returned by the server.

       beresp.ttl
              The object's remaining time to live, in seconds. beresp.ttl is writable.

       beresp.grace
              Set to a period to enable grace.

       beresp.saintmode
              Set to a period to enable saint mode.

       beresp.backend.name
              Name of the backend this response was fetched from.

       beresp.backend.ip
              IP of the backend this response was fetched from.

       beresp.backend.port
              Port of the backend this response was fetched from.

       beresp.storage
              Set to force Varnish to save this object to a particular storage backend.

       After the object is entered into the cache, the following (mostly read-only) variables are
       available when the object has been located in cache, typically in vcl_hit and vcl_deliver.

       obj.proto
              The HTTP protocol version used when the object was retrieved.

       obj.status
              The HTTP status code returned by the server.

       obj.response
              The HTTP status message returned by the server.

       obj.ttl
              The object's remaining time to live, in seconds. obj.ttl is writable.

       obj.lastuse
              The approximate time elapsed since the object was last requests, in seconds.

       obj.hits
              The  approximate  number  of  times  the  object  has  been delivered. A value of 0
              indicates a cache miss.

       obj.grace
              The object's grace period in seconds. obj.grace is writable.

       obj.http.header
              The corresponding HTTP header.

       The following variables are available while determining the hash key of an object:

       req.hash
              The hash key used to refer to an object in the cache.  Used when both reading  from
              and writing to the cache.

       The following variables are available while preparing a response to the client:

       resp.proto
              The HTTP protocol version to use for the response.

       resp.status
              The HTTP status code that will be returned.

       resp.response
              The HTTP status message that will be returned.

       resp.http.header
              The corresponding HTTP header.

       Values may be assigned to variables using the set keyword::

       sub vcl_recv {
         # Normalize the Host: header
         if (req.http.host ~ "(?i)^(www.)?example.com$") {
           set req.http.host = "www.example.com";
         }
       }

       HTTP headers can be removed entirely using the remove keyword::

       sub vcl_fetch {
         # Don't cache cookies
         remove beresp.http.Set-Cookie;
       }

   Grace and saint mode
       If  the  backend  takes a long time to generate an object there is a risk of a thread pile
       up.  In order to prevent this you can enable grace.   This  allows  varnish  to  serve  an
       expired version of the object while a fresh object is being generated by the backend.

       The  following  vcl code will make Varnish serve expired objects.  All object will be kept
       up to two minutes past their expiration time or a fresh object is generated.:

       sub vcl_recv {
         set req.grace = 2m;
       }
       sub vcl_fetch {
         set beresp.grace = 2m;
       }

       Saint mode is similar to grace mode and relies on the same  infrastructure  but  functions
       differently. You can add VCL code to vcl_fetch to see whether or not you like the response
       coming from the backend. If you find that the response is  not  appropriate  you  can  set
       beresp.saintmode  to a time limit and call restart. Varnish will then retry other backends
       to try to fetch the object again.

       If there are no more backends or if you hit max_restarts and we have  an  object  that  is
       younger than what you set beresp.saintmode to be Varnish will serve the object, even if it
       is stale.

EXAMPLES

       The following code is the equivalent of the default configuration with the backend address
       set to "backend.example.com" and no backend port specified::

       backend default {
        .host = "backend.example.com";
        .port = "http";
       }

       /*-
        * Copyright (c) 2006 Verdens Gang AS
        * Copyright (c) 2006-2011 Varnish Software AS
        * All rights reserved.
        *
        * Author: Poul-Henning Kamp <phk@phk.freebsd.dk>
        *
        * Redistribution and use in source and binary forms, with or without
        * modification, are permitted provided that the following conditions
        * are met:
        * 1. Redistributions of source code must retain the above copyright
        *    notice, this list of conditions and the following disclaimer.
        * 2. Redistributions in binary form must reproduce the above copyright
        *    notice, this list of conditions and the following disclaimer in the
        *    documentation and/or other materials provided with the distribution.
        *
        * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
        * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
        * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE
        * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
        * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
        * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
        * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
        * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
        * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
        * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        *
        * The default VCL code.
        *
        * NB! You do NOT need to copy & paste all of these functions into your
        * own vcl code, if you do not provide a definition of one of these
        * functions, the compiler will automatically fall back to the default
        * code from this file.
        *
        * This code will be prefixed with a backend declaration built from the
        * -b argument.
        */

       sub vcl_recv {
           if (req.restarts == 0) {
               if (req.http.x-forwarded-for) {
                   set req.http.X-Forwarded-For =
                       req.http.X-Forwarded-For + ", " + client.ip;
               } else {
                   set req.http.X-Forwarded-For = client.ip;
               }
           }
           if (req.request != "GET" &&
             req.request != "HEAD" &&
             req.request != "PUT" &&
             req.request != "POST" &&
             req.request != "TRACE" &&
             req.request != "OPTIONS" &&
             req.request != "DELETE") {
               /* Non-RFC2616 or CONNECT which is weird. */
               return (pipe);
           }
           if (req.request != "GET" && req.request != "HEAD") {
               /* We only deal with GET and HEAD by default */
               return (pass);
           }
           if (req.http.Authorization || req.http.Cookie) {
               /* Not cacheable by default */
               return (pass);
           }
           return (lookup);
       }

       sub vcl_pipe {
           # Note that only the first request to the backend will have
           # X-Forwarded-For set.  If you use X-Forwarded-For and want to
           # have it set for all requests, make sure to have:
           # set bereq.http.connection = "close";
           # here.  It is not set by default as it might break some broken web
           # applications, like IIS with NTLM authentication.
           return (pipe);
       }

       sub vcl_pass {
           return (pass);
       }

       sub vcl_hash {
           hash_data(req.url);
           if (req.http.host) {
               hash_data(req.http.host);
           } else {
               hash_data(server.ip);
           }
           return (hash);
       }

       sub vcl_hit {
           return (deliver);
       }

       sub vcl_miss {
           return (fetch);
       }

       sub vcl_fetch {
           if (beresp.ttl <= 0s ||
               beresp.http.Set-Cookie ||
               beresp.http.Vary == "*") {
                       /*
                        * Mark as "Hit-For-Pass" for the next 2 minutes
                        */
                       set beresp.ttl = 120 s;
                       return (hit_for_pass);
           }
           return (deliver);
       }

       sub vcl_deliver {
           return (deliver);
       }

       sub vcl_error {
           set obj.http.Content-Type = "text/html; charset=utf-8";
           set obj.http.Retry-After = "5";
           synthetic {"
       <?xml version="1.0" encoding="utf-8"?>
       <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
       <html>
         <head>
           <title>"} + obj.status + " " + obj.response + {"</title>
         </head>
         <body>
           <h1>Error "} + obj.status + " " + obj.response + {"</h1>
           <p>"} + obj.response + {"</p>
           <h3>Guru Meditation:</h3>
           <p>XID: "} + req.xid + {"</p>
           <hr>
           <p>Varnish cache server</p>
         </body>
       </html>
       "};
           return (deliver);
       }

       sub vcl_init {
               return (ok);
       }

       sub vcl_fini {
               return (ok);
       }

       The  following example shows how to support multiple sites running on separate backends in
       the same Varnish instance, by selecting backends based on the request URL::

       backend www {
         .host = "www.example.com";
         .port = "80";
       }

       backend images {
         .host = "images.example.com";
         .port = "80";
       }

       sub vcl_recv {
         if (req.http.host ~ "(?i)^(www.)?example.com$") {
           set req.http.host = "www.example.com";
           set req.backend = www;
         } elsif (req.http.host ~ "(?i)^images.example.com$") {
           set req.backend = images;
         } else {
           error 404 "Unknown virtual host";
         }
       }

       The following snippet demonstrates how to force a minimum TTL for
       all documents.  Note that this is not the same as setting the
       default_ttl run-time parameter, as that only affects document for
       which the backend did not specify a TTL:::

       import std; # needed for std.log

       sub vcl_fetch {
         if (beresp.ttl < 120s) {
           std.log("Adjusting TTL");
           set beresp.ttl = 120s;
         }
       }

       The following snippet demonstrates how to force  Varnish  to  cache  documents  even  when
       cookies are present::

       sub vcl_recv {
         if (req.request == "GET" && req.http.cookie) {
            return(lookup);
         }
       }

       sub vcl_fetch {
         if (beresp.http.Set-Cookie) {
            return(deliver);
        }
       }

       The  following  code  implements  the  HTTP  PURGE  method  as  used  by  Squid for object
       invalidation::

       acl purge {
         "localhost";
         "192.0.2.1"/24;
       }

       sub vcl_recv {
         if (req.request == "PURGE") {
           if (!client.ip ~ purge) {
             error 405 "Not allowed.";
           }
           return(lookup);
         }
       }

       sub vcl_hit {
         if (req.request == "PURGE") {
           purge;
           error 200 "Purged.";
         }
       }

       sub vcl_miss {
         if (req.request == "PURGE") {
           purge;
           error 200 "Purged.";
         }
       }

SEE ALSO

       · varnishd(1)

       · vmod_std(7)

HISTORY

       VCL was developed by Poul-Henning Kamp in cooperation with Verdens Gang AS, Redpill Linpro
       and  Varnish  Software.   This  manual  page  was written by Dag-Erling Smørgrav and later
       edited by Poul-Henning Kamp and Per Buer.

COPYRIGHT

       This document is licensed under the same  license  as  Varnish  itself.  See  LICENSE  for
       details.

       · Copyright (c) 2006 Verdens Gang AS

       · Copyright (c) 2006-2011 Varnish Software AS

AUTHOR

       Dag-Erling Smørgrav, Poul-Henning Kamp, Kristian Lyngstøl, Per Buer