Kristian Lyngstol's Blog

A free software-hacker's blog

My blog is now at

I’ve moved to

Hopefully this is the last time I move. I own the domain, control the server and software etc, so I should be good.

Please update your bookmarks, and sorry for the inconvenience. (Leaving this as a varnish tag so people only reading that will catch it)

The Varnish Book

In 2008 Tollef Fog Heen wrote the initial slides used for our first Varnish System Administration training course. Since then, I’ve been the principal maintainer and author of the material. We contracted Jérôme Renard ( to adapt the course for web developers in 2011 and I’ve spent some time pulling it all together into one coherent book after that.

Today we make the Varnish Book available on-line under a Creative Commons CC-BY-NC-SA license.

See for the overview page, or for the sphinx-rendered HTML variant.

The All-important content!

The book contains all the content we use for both the system administration course and the web developer course. While each of those courses omit some chapters (Sysadmin omits HTTP and Content Composition while Webdev omits the Tuning and Saving a Request chapters), the content is structured with this in mind.

The book does not teach you everything about Varnish.

If you read the book and perform the exercises (without cheating!) you will:

  • Understand basic Varnish configuration and administration
  • Know when modifying parameters is sensible
  • Have extensive understanding of VCL as a state engine and language
  • Understand how caching in HTTP affects Varnish, intermediary caches and browser caches
  • Know how to use Varnish to recover from or prevent error-situations
  • Have in-depth knowledge of the different methods of cache-invalidation that Varnish can provide
  • Know several good ways to approach cookies and user-specific content
  • Know of Edge Side Includes
  • Much more!

I’ve gradually restructured the book to be about specific tasks instead of specific features. Because of that, there are several features or techniques that are intentionally left out or down-played to make room for more vital concepts. This has been a gradual transition, and I’m still not entirely satisfied, but I believe this approach to learning Varnish is much more effective than trying to just teach you the facts.

One of my favorite examples of this is probably the Cache Invalidation chapter. We used to cover the equivalent of purging in the VCL chapters, since it is a simple enough feature, then cover banning in a separate chapter. The problem with that mentality is that when you are setting up Varnish, you don’t think “I need to write VCL”. You think “I need to figure out how to invalidate my cache” or “how do I make Varnish fall back to a different web server if the first one failed”.

I have learned a great deal about Varnish, about how people learn and about the web in general while holding these training courses and writing this book. I hope that by releasing it in the open, even more people will get to know Varnish.

Future Content

The book will continue to change. We at Varnish Software will update it for new versions of Varnish and take care of general maintenance.

I hope that we will also get some significant feedback from all you people out there who will read it. We appreciate everything from general evaluation and proof reading to more in-depth discussions.

One of the more recent topics I want to cover in the book is Varnish Modules. This is still quite new, so I’m in no rush. I still haven’t decided what that chapter should cover. It might be about available vmods and practical usage of them, or we might go more in depth and talk about how to start writing your own. I really don’t know.

An other topic I really wish to expand upon is content composition. The material Jerome provided for us was excellent, but I wish to go broader and also make it available in a couple of other languages than just PHP. There is some work in this area already, I just can’t say much more about it yet…

You will probably also see rewrites of the first chapter and the Programs-chapter in the near future. They are both overdue for a brush-up.

In the end, though, this a book that will continue to evolve as long as people take interest. What it covers will be defined largely based on feedback from course participants, feedback from people reading it on-line and the resources needed to implement those changes.


We chose a CC-BY-NC-SA license because we both want to make the material available to as many people as possible, and make sure that we don’t put our self out of the training business by providing a ready-made course for potential competitors.

Being of of those people who actually read licenses and try to interpret their legal ramifications, I’ve obviously also read the CC-BY-NC-SA license we use. It is (intentionally) vague when it comes to specifying what “non-commercial” means. What I interpret it as with regards to our training material is that you can read it as much as you want regardless of whether you are at work or what commercial benefits you have from understanding the content. You can also hold courses in non-profit settings (your local LUG for instance), and some internal training will probably be a non-issue too. However, the moment you offer training for a profit to other parties, you’re violating the license. You’ll also be violating it if you print and sell the book for a profit. Printing and selling it to cover the cost of printing is allowed (it’s one of the few things where the license actually clarifies this).

Since we are using a “NC”-license, we’ll also be asking for copyright assignment and/or a contributor’s agreement if you wish to contribute significantly. This is so we can use your material in commercial activities. Exactly how this will be done is not yet clarified.

One last point: If you are contributing to the documentation we keep at, we will not consider it a breach of license if you borrow ideas from the book. Our goal is to make sure the book interacts well with the other documentation while covering our expenses.

Varnish Training

As anyone who’s worked with me should realize by now, I’m big on documentation, be it source code comments or other types of documentation. The only reason I’m not more active in the documentation section of Varnish Cache is because I’ve maintained our (Varnish Software’s) training material ever since Tollef Fog Heen wrote the initial slides in 2009.

I’ve held the course more times than I can remember, and usually done improvements after every course. Others have also held the course, including Redpill Linpro’s Kacper Wysocki, maintainer of security.vcl and Magnus Hagander (Postgresql god/swede). Feedback and gradual improvements have turned a set of slides into a pretty good course material.

We recently started holding on-line courses too. This revealed several new challenges. The obvious challenges are things like getting basic voice communication working (it sounds easy, but you’d be amazed…). It was also interesting when I held the course in my apartment on Australian time, and my ISP decided to perform maintenance on my cable modem (it was 2AM local, after all). So I’ve had to hold the course on a 3G connection, communicating with Australia. Fun. Then there’s the lack of or severely reduced feedback, which presents challenges in how we do exercises and generally deal with the course. In a class room I can easily determine if the participants are able to keep up, if I’m going too slow or too fast and whether or not a subject is more interesting than an other. All of that is, at best, very difficult in an on-line session.

The last few weeks I’ve finally gotten around to merging the sysadmin course with the web development course that Jérôme Renard has written for us. It proved the perfect opportunity to give the course an other big update. While the course was already updated for Varnish 3, I’ve made several other Varnish 3-related additions. More importantly is that the flow of the course has changed from one oriented on Varnish functionality to tasks you wish to accomplish with Varnish. Instead of teaching you about Varnish architecture first, then Varnish parameters, the course now has a chapter devoted to Tuning.

Instead of just throwing in purging or banning when talking about VCL, there’s now a chapter called Cache Invalidation, that attempts to give broader understanding of the alternatives you have and when to use which solution. Similarly, there’s a chapter called Saving The Request, which starts out with the core Grace mechanisms, moves on to health checks, saint mode, req.hash_always_miss, directors and more.

There are several reasons I write about this. First of all: I’m very excited about the material. I’ve worked on it regularly for several years, doing everything from hacking rst2s5, tweaking the type setting and design to updating the content, reorganizing the course and of course holding it. It may seem like one big marketing stunt, but I can promise you that I never blog about something I’m not passionate about, regardless of whether it is work-related or not.

The other reason is that I’m holding the course next week. This will be the first time we hold it using the changed structure. I would have wanted to hold it in a class room first, but holding it on-line is still exciting.

If you wish to participate, head over to and convince your boss it will be awesome!

Varnish 3.0.0 – RSN!

Varnish 3.0.0 beta2 was just released, and we’re aiming for 3.0.0 next week.

The release date is set for Thursday the 16th (next week(June, 2011, for the potential future archive crawlers)), and several release parties are planned. Varnish Software will be present in Santa Clara, London and Oslo, but numerous parties are planned all around the world.

This will be a very special day for everyone in Varnish Software. Varnish 2.0.0 was released roughly the same week I started working at Redpill Linpro, before I was really involved with Varnish, and I still regret that I didn’t snatch one of those fancy 2.0-t-shirts.

What’s new?

While there are too many news to mention, there are two that stand out more than anything.

The first is gzip compression and the second is the Varnish module-architecture, or simply vmods. That most of ESI has been re-factored under the hood will be evident in future releases, and the same goes for streaming delivery.


– “What, you don’t already have compression?!”

Remember, Varnish is a caching service. Most of the time you don’t need it to do the compression, because the web server will do it for you. But there are good reasons for why you want it. ESI is the primary use-case.

With ESI, Varnish needs to parse the content, and it can’t do that if it doesn’t understand the transfer encoding. With Varnish 2.1, you have to send uncompressed data to Varnish if you want to use ESI. This means you have to either deliver uncompressed content to your clients, or use yet an other service in front of Varnish.

But let me get a bit technical, because Varnish 3.0’s compression is pretty awe-inspiring.

So with ESI, you have multiple, individually cached elements that make up a single user-visible page. So what we could do, is glue it all together and compress it before we send it. The downside is that we’ll do the compression over and over. An alternative would be to cache the compressed result as long as the individual elements are unchanged, but that will require more space and more complexity.

So what does Varnish 3.0 does? It stores the elements compressed, modifies the right gzip-bits and glues it all together on the fly, without decompressing it. If a single element is changed, only that element needs to be updated. This is probably the best solution, even if the complexity of meddling with binary gzip headers directly can lead to some pretty tricky code. I challenge you to find a solution that handles compression in a smarter way.

Varnish 3.0 also does decompression. If your browser doesn’t support compression (Possibly a script or other tool, real browsers support compression), Varnish will decompress the object for you on the fly. This is an other huge improvement over Varnish 2.1. In Varnish 2.1, this is solved using Vary: and storing different copies of the same object based on compression.

We can also do the same with the backend-data: If ESI needs to read the data, Varnish 3.0 can decompress it on the fly, parse it, then re-compress it before storing it.

And for you, the user, the complexity is fairly non-existent. Push the button, remove that nginx(no hard feelings)server you had doing compression, ????, profit!


VCL, the Varnish Configuration Language, is a flexible way of configuring Varnish. Since it is already translated from VCL to C, the compiled and linked in to the running Varnish instance, VCL has “always” had in-line C: Anywhere you want to, you can tell the VCL compiler that this is pure C code, and pass it directly to the compiler instead of trying to translate from VCL to C first. This was mainly provided because:

1. It didn’t add any complexity and was actually less work.
2. It provided an escape chute for features we didn’t want in Varnish-proper, but were valid for some users.

What features could that be? Syslog-support, geoip-integration, cryptographic verification of authorization headers, etc.

It turned out to be very useful, but impractical and difficult to re-use. Since it was all glued to your VCL, it meant that you had to stick C code in the middle of your regular configuration, and it made it very hard to combine two different features if you didn’t know C yourself. And linking towards external libraries required parameter changes.

Enter varnish modules.

Simply put, vmods are a way of letting you do the same thing you can do with in-line C, but in a more sustainable manner. A vmod will typically have a few functions exposed to VCL, and the VCL just has to declare that it imports the vmod to use the functions without a single line of C-code in your VCL.

This also means that the vmod has its own build system, own linking process, flexible development environment and are much easier to share.

In the time to come, I expect us to have a community-site for vmods. I also expect that you will see a lot of minor yet important changes to Varnish during the Varnish 3.0-cycle that exposes more of the internal varnish utilities so vmods can use them.

Small disclaimer, though: There is no API guarantee. We don’t wish to slow the pace of Varnish-development by restricting what we can change. That said, we wont tear things apart just to see our vmod-contributors bleed.

I plan to write a blog post on vmod-hacking in the near future, so expect more detail there.

Finishing words

Varnish 1.0 was, as any 1.0-release is, important. I was not involved with the project back then, but as I understand it, Varnish 1 was very much tailored to a specific site, or type of site.

With Varnish 2.0, Varnish became useful for anyone with a high-traffic site. The 2.0-series was a good release-series, adding a healthy mixture of bug fixes and non-intrusive features with each release. But constantly focused on real-world usage. We also saw the first Varnish User Group meeting during that time.

Varnish 2.1 has been a sort of intermittent release. Director-refactoring, ESI and to a certain degree persistent storage paved the way for architectural changes that had to be done. Meanwhile, the user-base really exploded.

Now, with Varnish 3.0.0 coming out, we are already seeing how useful vmods are for Varnish Software-customers like Softonic, who’re sponsoring a VMOD to allow header-modification targeted at the Set-Cookie header (which can’t be treated like the RFC2616 specifies, due to how this has been implemented historically). Doing this in a vmod allows the VCL to remain clean. It also lets us share the code that isn’t site-specific but widely useful, since it is all contained in a header vmod(Still under development). Gzip also means there are no drawbacks to using ESI with Varnish. You don’t need to add a second service to compress data.

It all boils down to Varnish being a more useful part of your architecture. It’s easy to get fast and maintainable C-code in there if you need it, you can even pay someone to write just that bit for you. Without being confined to Varnish’ own road map and release cycle. There are no longer any downsides to using ESI. It’s fast. It’s free software. There are professional service and support offerings available. Varnish follow standards – unless you tell it not to. And so forth.

I’m not usually one to pat myself too much on the back, but as I’m writing this, I feel proud to be part of the team that gives you Varnish 3.0.

If you’re in Oslo, I’ll see you next Thursday!


Get every new post delivered to your Inbox.