This should really be an exercise and not a demo. I've usually turned it into an exercise, and it's a much better way to gain actual understanding of how grace really works - which can be tricky wen you're new to it.

As agreed under VUG6 in London, we should make the license of the examples explicit, so the examples can be used both in the book as well as in the documentation (which ships with Varnish Cache).

The FreeBSD license will apply for the /vcl and /material/webdev directories, as all VCL and PHP examples are contained there. Shall we do this by adding the license text to the current LICENSE file or by adding a LICENSE file to each directory?

For Vary, the admin course currently just says "The handling of the Vary-header is separate from the cache hash." in a note. There really needs to be some explanation of how it's actually handled (possibly in a different section of course, but somewhere in the admin course).

Similar to sound-issues...

There are times when screen sharing simply does not work. Clicking the screen sharing doesn't do anything. A quick restart of bbb seems to fix this.

Not sure where the beeping comes from, but it seems that regardless of what I do, it makes a sound when I interact with the sound inside of bbb - part of why I don't use it.

call, set, unset and return are not functions but keywords and should not be listed under VCL built-in functions.

It's currently somewhat manual, particularly with regards to the request flow chart. This needs fixing.

Things to add:

• Use of domains: "www.cnn.com" / 24
• If you put an entry in (...) it ignores it if DNS does not resolve.
• IPv6
• Blindingly fast, long lists are perfectly OK.
• Good place to show example of "include" in VCL

There is no coverage at all in the course about the gzip functionality in Varnish 3. Yet, this is something I run into quite often with clients who consider it a very useful feature in Varnish. It's also pretty simple - but it should warrant at least a small section with some best practices and how to set it up, etc.

To complete the course, trainees need to the following software:

• Varnish Cache 4.x or Varnish Cache Plus 4.x
• Apache/2.4 or later
• HTTPie 0.8.0 or later
• PHP 5.4 or later
• curl - command line tool for transferring data with URL syntax

Trainees receive access to a VM without this software preinstalled. The book explains step by step how to install and configure them. An advantage of this approach is to spend as less time as possible to get started.

@dridi commented that it would be useful to have the installation process as an exercise to gauge the trainees.

Please comment if you have a strong opinion.

Hi,

I tried to compile the V4.2 release but I'm getting this error:

Couldn't include build/exercises/complete-rewrite_urls_and_headers.rst
make: *** [build/merged_book.rst] Error 2

Any idea what went wrong?

The ban (purges)-chapter isn't all that good, and should probably be re-organized a bit. And eventually renamed to bans.

The Varnish Plus repository log shows that RedHat users are about double than Ubuntu/Debian users. Therefore, the book should prioritise explanations and commands for RedHat instead of Ubuntu.

The finishing words need some real love. It's currently part of the course which I haven't properly re-factored.

Screenshots may be added to improve the description of vagent2 or in the VAC section.

Random and Round-Robin are the basic directors, and should be explained more thoroughly.

The pickchapter.sh and splitchapters.sh does not exists in directory Varnish-Book/util but exists a simbolic link for this files (/home/kristian/Documents/Source/training/util/pickchapter.sh and /home/kristian/Documents/Source/training/util/splitchapters.sh) in path Varnish-Book/src/util

Also tries to parse urls, which is a bother for VCL snippets. Things like | seem to be hard to use.

Perhaps a "practical VCL" bit? Or more exercises that does exactly this. cookie-removal is pretty common.

Grace requires a more thorough explanation.

The VCL is currently built and tested, but it isn't extracted from varnish, so it can get out of sync.

This issue includes the removal or reallocation of the testbed installation guidelines.

Right now, varnishtop is only covered in the appendix. Such a useful tool really should be covered earlier in the book, and in more detail.

Comment from @KristianLyng:

There's a parameter called vcc_err_unref that defaults to 'on'. People some time want to have stuff like backends defined, but not use them, and that means turning that parameter off. It is a pretty common request for people with large server collections, since they may want to have backends they just use every now and then, without having to comment them in and out every time.

Some sections have no "slide" parts, but only handout content. Also, some slides have only one bullet. All sections should have more than one bullet highlighting the important take away points.

httpie is not consistent across all Linux distributions. Some customers might not be willing to install it either.

All the director-stuff pretty much needs to be re-done. I've created issues for each, but it all needs to be re-factored.

Saintmode requires some explanation....

I think providing an option for epub, would be really useful because generating an epub form a pdf file is really hard to get right, and after all we have the source :)
I've played a bit with the Makefile and was able to get it working. I don't have that much experience with sphinx so this was a bit trial and error.
I've looked into sphinx a bit, and when generating the conf-py.in (Varnish Book documentation build configuration file) we have the option in sphinx-quickstart to enable the epub support

Sphinx can also add configuration for epub output:
 Do you want to use the epub builder (y/n) [n]: y

Enabling this, would be enough from what I've checked.

Without doing this I was still able to make it work just by changing a bit the make file, and copying bit from the sphinx task.

epub: ${common} src/conf.py
    for a in ui util/* vcl material build/version.rst ; do \
        if [ ! -e src/$$a ]; then \
            ln -s ${PWD}/$$a src/$$a ;\
        fi; \
    done;

#This loop should be improved! This clears out frontpage.rst and printheaders.rst and creates wrong pdf later.
    for a in src/util/frontpage.rst src/util/printheaders.rst; do \
        rm $$a; \
        touch $$a; \
    done

#Splits chapters into individual files, and creates the index page for sphinx.
    mkdir -p src/build/chapters
    ln -sf ${PWD}/ui build/chapters/

#update references in tables:
    mkdir -p src/build/chapters/tables
    for a in tables/*; do \
        util/rst2sphinxparser_tables.awk -v dst="src/build/chapters/"$$a < ${PWD}/$$a; \
    done

    util/rst2sphinxparser.igawk -v dst=${PWD}/src/ < ${mergedrst}

#Removes '.. class:: handout' from src/*.rst
    sed -i 's/\.\. class:: handout//' src/*.rst

    sphinx-build -b epub -d build/doctrees   src/ build/epub

this was obviously a rip off from the sphinx task, but I only wanted to test if it worked.
Actually the only difference is the line:

 sphinx-build -b epub -d build/doctrees   src/ build/epub

I was able to create a epub with this.

$ make
mkdir -p build
./util/version.sh > build/version.rst
Building PDFs for book...
gawk: fatal: cannot use gawk builtin include' as variable name Building PDF slides for book... gawk: fatal: cannot use gawk builtininclude' as variable name

I've experienced that multihead setup has confused screensharing. It resulted in the rectangle for selecting the area to share being displayed on a different monitor than what was eventually shared. It was fairly consistent and predictable, but icky.

The VCL is currently 2.1-compatible, but should be updated for 3.0 Soon [tm].

NEWS and README were written with tar-balls and 'plain' git in mind. It should be re-factored so the most relevant information is easily available on the github front-page.

In chapter 1 there are two places where we mention supported platforms(1.1 and 1.2). The reason for this is that one mentions support for Varnish Plus while the other talks about Varnish Cache.

Listings for both Varnish Plus and Varnish Cache should be under 1.2 as we do the comparison between these in that chapter anyway, so having that also there should make sense.

I can send a pull request if you agree with my idea here.

This is an old suggestion by Kristian Lyngstøl. Instructors, would this example be valuable for most of your trainees? If yes, please comment what exactly the example should show/teach.

Not a big issue. My workaround is to not stop the client, but use mute instead. Worth knowing.

While having a chat on IRC a request, that makes a lot of sense, came from a reader of the book:

varnish user: ruben_varnish: indeed. There's a VCL examples that should be more promoted too
varnish user: there're valuable snippets there
varnish user: for example, the one that fixes the Vary: User-agent
...
varnish user: bring the VCLExamples to the book
varnish user: but revise them
varnish user: they're not standardized
varnish user: there're different approaches of doing the same thing

There you have something to include in the next version of it.