Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time

Training material and related tools

This repository contains:

  • Training material used for Varnish Plus training
  • Source for the slides and book version
  • A snapshot of munin graphs for use by instructors.
  • PHP example-code for testing Varnish
  • Build system for said training material

This is the training material Varnish Software uses for professional Varnish training courses. It is made available under a Creative Commons CC-BY-NC-SA license (see the LICENSE file for details) as a book.

The build system produces the book in PDF and HTML formats. The PDF format includes two editions, one as the book for trainees, and the other as slides for the trainer. You can download this book in PDF format from


  • build/ - Created on make, contains PDF output, html-output and necessary images
  • Makefile
  • material/ - PHP files, mainly used by the web-dev material
  • misc/ - Contains strange stuff. Including the old course (Linpro-source) and a patch for rst2s5 needed (and a pre-patched version).
  • munin/ - Anonymized munin graphs for instructors
  • NEWS - List of changes instructors should be be aware of from version to version.
  • README - This file
  • TODO
  • ui/ - Images, style-definitions for PDFs and CSS for the slides.
  • util/ - Headers for the rst, tool to make version.rst, strip-class to remove an rst-class (for generating slides as PDF instead of s5).
  • varnish_book.rst - course itself
  • vcl/ - VCL files used in the course. Not a copy. Included directly as-is, and verified by make check. (note: If 'backend' is missing, a generic backend will be added on the fly during make check).
  • src/ - Resource files for sphinx to export the book in HTML version. This folder contains a Makefile to build the book in different formats. Enter to the directory and type make to see the building targets.

Building the material

Install the following packages with their dependencies.

  • rst2pdf
  • gawk
  • git
  • make
  • graphviz
  • php5
  • sphinx 1.3 or later
  • python-docutils
  • inkscape
  • Open Sans font type

You also need the "Open Source" font type. To check whether you have it, type fc-match "Open Sans" in the terminal. The command should output OpenSans-Regular.ttf: "Open Sans" "Regular". Otherwise, do the following:

$ wget
$ sudo unzip open-sans -d /usr/local/share/fonts/truetype/
$ rm open-sans
$ fc-cache
$ fc-match "Open Sans"

Download the source code of this book:

git clone

Compile the book:

make book

All build-stuff is handled by make. The following is an incomplete list of targets:

make book
Builds book in PDF format
make sphinx
Builds book in HTML and ePub format
make slides
Builds slides in PDF format. This slides are to be used in a training course.
make clean
removes build/
make util/param.rst
Updates the default values of your Varnish installation.
These values are the ones to be used in your book building.
make sourceupdate
Calls util/param.rst rule and will call other rules to update the sources of the book.

Updating the training material

Read NEWS, and make sure you always add significant content changes in this file, so the instructor(s) can keep track of changes without reading commit logs.

Try to use only tip, warning and note boxes.

To change the layout, change ui/ or ui/

The syntax for indirect hyperlink targets (double underscores __) is not the same for rst as for sphinx. Thefore, for simplicity, avoid them. More than two refereces per sentence is not supported by rst2sphinxparser.igawk.

Figures and tables must have a counter right before their directive. The counter must be as the following example:

.. figure 1


.. table 1

Use git-tag every time that the book is printed and distributed.

Known issues

This subsection includes known issues for building the book in different formats.

Building with sphinx

  • List of figures and list of tables do not work when the figure or table caption includes a reference. This is a limitation to create the PDF with sphinx.
  • Fonts are not resized in notes or other cases such :class: tinycode.


This material is provided under a CC-BY-NC-SA license. The license is available from:

And a copy of the license is available in the LICENSE file.

Clarification: The Non-Commercial clause of the CC-BY-NC-SA license is intentionally vague in the original license. Varnish Software does not interpret reading of the material as commercial, regardless of context (e.g: You can read the material at work, for the benefit of your self and the company). The Non-Commercial clause is intended to block competition with other commercial training offerings and to prohibit commercial printing and selling of the book. If you have any doubt as to how this should be interpreted, please contact for clarification before proceeding.