VCL is an acronym for Varnish Configuration Language. In a VCL file, you configure how Varnish should behave. Sample VCL files will be included in this Wiki at a later stage.
**Where is the documentation on VCL?**
Please see ``man 7 vcl``. There are also some real-world examples on
the `wiki <http://varnish-cache.org/wiki/VCLExamples>`_
**How do I load VCL file while Varnish is running?**
* Place the VCL file on the server
* Telnet into the managment port.
* do a "vcl.load <configname> <filename>" in managment interface. <configname> is whatever you would like to call your new configuration.
* do a "vcl.use <configname>" to start using your new config.
**Should I use ''pipe'' or ''pass'' in my VCL code? What is the difference?**
When varnish does a ``pass`` it acts like a normal HTTP proxy. It
reads the request and pushes it onto the backend. The next HTTP
request can then be handled like any other.
``pipe`` is only used when Varnish for some reason can't handle the
``pass``. ``pipe`` reads the request, pushes in onty the backend
_only_ pushes bytes back and forth, with no other actions taken.
Since most HTTP clients do pipeline several requests into one
connection this might give you an undesirable result - as every
subsequent request will reuse the existing ``pipe``. Please see `this
article <http://www.varnish-cache.org/trac/wiki/VCLExamplePipe>` for
more details and a workaround.
Varnish versions prior to 2.0 does not support handling a request body
with ``pass`` mode, so in those releases ``pipe`` is required for
correct handling.
In 2.0 and later, ``pass`` will handle the request body correctly.
If you get 503 errors when making a request which is ``pass`` ed, make sure
that you're specifying the backend before returning from vcl_recv with ``pass``.
I think our best current guidance is that you go for a cost-effective
RAM configuration, something like 1-16GB, and an SSD.
Unless you positively know that you will need it, there is
little point in spending a fortune on a hand-sewn motherboard
that can fit several TB in special RAM blocks, riveted together
by leftover watch-makers in Switzerland.
On the other hand, if you plot your traffic in Gb/s, you probably
need all the RAM you can afford/get.
**How can I limit Varnish to use less RAM?**
You can not. Varnish operates in Virtual Memory and it is up to the
kernel to decide which process gets to use how much RAM to map the
virtual address-space of the process.
**How do I instruct varnish to ignore the query parameters and only cache one instance of an object?**
This can be achieved by removing the query parameters using a regexp::
sub vcl_recv {
set req.url = regsub(req.url, "\?.*", "");
}
**How can I force a refresh on a object cached by varnish?**
Refreshing is often called `purging
<http://dictionary.reference.com/browse/PURGE>`_ a document. You can
purge at least 2 different ways in Varnish:
1. Command line
From the command line you can write::
ban.url ^/$
to ban your / document. As you might see ban.url takes an `regular expression <http://en.wikipedia.org/wiki/Regular_expression>`_
as its argument. Hence the ``^`` and ``$`` at the front and end. If the ``^`` is omitted, all the documents ending in a ``/`` in the cache would be deleted.
So to delete all the documents in the cache, write::
ban.url .
at the command line.
2. HTTP PURGE
VCL code to allow HTTP PURGE is to be found `here <http://www.varnish-cache.org/wiki/VCLExamplePurging>`_. Note that this method does not support wildcard purging.
**How can I debug the requests of a single client?**
The "varnishlog" utility may produce a horrendous amount of output. To be able debug our own traffic can be useful.
The ReqStart token will include the client IP address. To see log entries matching this, type::
$ varnishlog -c -m ReqStart:192.0.2.123
To see the backend requests generated by a client IP address, we can match on the TxHeader token, since the IP address of the client is included in the X-Forwarded-For header in the request sent to the backend.
At the shell command line, type::
$ varnishlog -b -m TxHeader:192.0.2.123
**How can I rewrite URLS before they are sent to the backend?**
You can use the ``regsub()`` function to do this. Here's an example for zope, to rewrite URLs for the virtualhostmonster::
if (req.http.host ~ "^(www.)?example.com") {
set req.url = regsub(req.url, "^", "/VirtualHostBase/http/example.com:80/Sites/example.com/VirtualHostRoot");
}
**I have a site with many host names, how do I keep them from multiplying the cache?**
You can do this by normalizing the ``Host`` header for all your host names. Here's a VCL example::
if (req.http.host ~ "^(www.)?example.com") {
set req.http.host = "example.com";
}
**How do I do to alter the request going to the backend?**
You can use the ``bereq`` object for altering requests going to the backend, but you can only 'set' values to it. Therefore use req.url to build the request::
sub vcl_miss {
set bereq.url = regsub(req.url,"stream/","/");
return(fetch);
}
**How can I customize the error messages that Varnish returns?**
A custom error page can be generated by adding a ``vcl_error`` to your configuration file. The default error page looks like this::
sub vcl_error {
set obj.http.Content-Type = "text/html; charset=utf-8";
synthetic {"
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
Please see :ref:`tutorial-advanced_backend_servers-directors`.
Why ...
=======
**Why does it look like Varnish sends all requests to the backend? I thought it was a cache?**
Please see :ref:`tutorial-increasing_your_hitrate`.
**Why does Varnish require the system to have a C compiler?**
The :ref:`VCL <faq-vcl>` compiler generates C source as output (your
config file), and uses the systems C-compiler to compile that into a
shared library. If there is no C compiler, Varnish will not work.
**Isn't that security problem?**
The days when you could prevent people from running non-approved
programs by removing the C compiler from your system ended roughly
with the VAX 11/780 computer.
Troubleshooting
===============
**Why am I getting a cache hit, but a request is still going to my backend?**
Varnish has a feature called **hit for pass**, which is used when Varnish gets a response from the backend and finds out it cannot be cached. In such cases, Varnish will create a cache object that records that fact, so that the next request goes directly to "pass".
Since Varnish bundles multiple requests for the same URL to the backend, a common case where a client will get a **hit for pass** is:
* Client 1 requests url /foo
* Client 2..N request url /foo
* Varnish tasks a worker to fetch /foo for Client 1
* Client 2..N are now queued pending response from the worker
* Worker returns object to varnish which turns out to be non-cacheable.
* Client 2..N are now given the **hit for pass** object instructing them to go to the backend
The **hit for pass** object will stay cached for the duration of its ttl. This means that subsequent clients requesting /foo will be sent straight to the backend as long as the **hit for pass** object exists.
The :command:`varnishstat` can tell you how many **hit for pass** objects varnish has served. The default vcl will set ttl for a hit_for_pass object to 120s. But you can override this, using the following logic::
sub vcl_fetch {
if (!obj.cacheable) {
# Limit the lifetime of all 'hit for pass' objects to 10 seconds
**What is the purpose of the X-Varnish HTTP header?**
The X-Varnish HTTP header allows you to find the correct log-entries for the transaction. For a cache hit, X-Varnish will contain both the ID of the current request and the ID of the request that populated the cache. It makes debugging Varnish a lot easier.
**Does Varnish support compression?**
This is a simple question with a complicated answer; see `WIKI <http://varnish-cache.org/wiki/FAQ/Compression>`_.
**How do I add a HTTP header?**
To add a HTTP header, unless you want to add something about the client/request, it is best done in vcl_fetch as this means it will only be processed every time the object is fetched::
sub vcl_fetch {
# Add a unique header containing the cache servers IP address:
remove beresp.http.X-Varnish-IP;
set beresp.http.X-Varnish-IP = server.ip;
# Another header:
set beresp.http.Foo = "bar";
}
**How can I log the client IP address on the backend?**
All I see is the IP address of the varnish server. How can I log the client IP address?
We will need to add the IP address to a header used for the backend request, and configure the backend to log the content of this header instead of the address of the connecting client (which is the varnish server).
Varnish configuration::
sub vcl_recv {
# Add a unique header containing the client address
remove req.http.X-Forwarded-For;
set req.http.X-Forwarded-For = client.ip;
# [...]
}
For the apache configuration, we copy the "combined" log format to a new one we call "varnishcombined", for instance, and change the client IP field to use the content of the variable we set in the varnish configuration::
Varnish does not log to a file, but to shared memory log. Use the varnishlog utility to print the shared memory log or varnishncsa to present it in the Apache / NCSA "combined" log format.
