[master] 9a57367 Add sphinx doc about GZIP, ESI part still to be written

Poul-Henning Kamp phk at varnish-cache.org
Mon Jan 24 11:20:14 CET 2011

commit 9a57367ff5aa05929ca04c6fb5ebbc6fb2f7bd07
Author: Poul-Henning Kamp <phk at FreeBSD.org>
Date:   Mon Jan 24 10:19:52 2011 +0000

    Add sphinx doc about GZIP, ESI part still to be written

diff --git a/doc/sphinx/phk/gzip.rst b/doc/sphinx/phk/gzip.rst
new file mode 100644
index 0000000..77ba94f
--- /dev/null
+++ b/doc/sphinx/phk/gzip.rst
@@ -0,0 +1,92 @@
+.. _phk_gzip:
+How GZIP, and GZIP+ESI works in Varnish
+First of all, everything you read about GZIP here, is controlled by the
+	http_gzip_support
+Which defaults to "on" if you do not want Varnish to try to be smart
+about compression, set it to "off" instead.
+What does http_gzip_support do
+A request which is sent into 'pipe' or 'pass' mode from vcl_recv{}
+will not experience any difference, this processing only affects
+cache hit/miss requests.
+Unless vcl_recv{} results in "pipe" or "pass", we determine if the
+client is capable of receiving gzip'ed content.  The test amounts to:
+	Is there a Accept-Encoding header that mentions gzip, and if
+	is has a q=# number, is it larger than zero.
+Clients which can do gzip, gets their header rewritten to:
+	Accept-Encoding: gzip
+And clients which do not support gzip gets their Accept-Encoding header
+removed.  This ensures conformity with respect to Vary: strings during
+hash lookup.
+Varnish will not do any other types of compressions than gzip, in particular
+we will not do deflate, as there are browser bugs in that case.
+Before vcl_hit{} is called, the backend requests Accept-Encoding is
+always set to:
+	Accept-Encoding: gzip
+To always entice the backend into sending us gzip'ed content.
+Varnish will not gzip any content on its own (but see below), we trust
+the backend to know what content can be sensibly gzip'ed (html) and what
+can not (jpeg)
+If in vcl_fetch{} we find out that we are trying to deliver a gzip'ed object
+to a client that has not indicated willingness to receive gzip, we will
+ungzip the object during deliver.
+Tuning, tweaking and frobbing
+In vcl_recv{} you have a chance t modify the clients Accept-Encoding: header
+before anything else happens.
+In vcl_pass{} the clients Accept-Encoding header is copied to the
+backend request unchanged.
+Even if the client does not support gzip, you can force the A-C header
+to "gzip" to save bandwidth between the backend and varnish, varnish will
+gunzip the object before delivering to the client.
+In vcl_fetch{} two new variables allow you to modify the gzip-ness of
+objects during fetch:
+	set beresp.do_gunzip = true;
+Will make varnish gunzip an already gzip'ed object from the backend during
+fetch.  (I have no idea why/when you would use this...)
+	set beresp.do_gzip = true;
+Will make varnish gzip the object during fetch from the backend, provided
+the backend didn't send us a gzip'ed object.
+Remember that a lot of content types cannot sensibly be gziped, most
+notably compressed image formats like jpeg, png and similar, so a
+typical use would be:
+	sub vcl_fetch {
+		if (req.url ~ "html$") {
+			set beresp.do_gzip = true;
+		}
+	}
diff --git a/doc/sphinx/phk/index.rst b/doc/sphinx/phk/index.rst
index 9eecca8..e07e50e 100644
--- a/doc/sphinx/phk/index.rst
+++ b/doc/sphinx/phk/index.rst
@@ -8,6 +8,7 @@ You may or may not want to know what Poul-Henning think.
 .. toctree::
+	gzip.rst

More information about the varnish-commit mailing list