Kristian Lyngstøl's Blog

The Varnish Book

Posted on 2012-03-28

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 (http://39web.fr)) 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.

http://kly.no/Blog/varnish-book-screenie.png

See http://www.varnish-software.com/static/book/ 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 (https://www.varnish-software.com) 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.

License

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 www.varnish-cache.org, 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.