..
.. NB:  This file is machine generated, DO NOT EDIT!
..
.. Edit ./vmod_etag.vcc and run make instead
..

.. role:: ref(emphasis)

=========
vmod_etag
=========

-------------------
Varnish ETag Module
-------------------

:Manual section: 3

DESCRIPTION
===========

This vmod adds a `beresp.filter`_ (see aka Varnish Fetch Processor /
VFP) to generate ETags on the way into the Varnish Cache.

.. _`beresp.filter`: http://varnish-cache.org/docs/trunk/reference/vcl.html#beresp

It is strongly recommended to use this vmod from VCL as shown in the `SYNOPSIS`_

ETag generation is enabled by adding ``etag`` to ``beresp.filters`` as
shown in the example above.

The ETag format is the string ``"vetag`` followed by 64 hexadecimal
characters representing a SHA256 hash over the response body and a
closing quote ``"``. The ``"vetag`` prefix is used to identify
incompletely generated ETags as explained below.

Usage notes:

* For *streaming*, an ETag can not be generated, because, by design,
  the response headers are being sent before the backend response is
  complete.

  The VCL template in the `SYNOPSIS`_ thus contains
  ``set beresp.do_stream = false`` to disable streaming when the ``etag``
  filter is activated.

  The ``vcl_deliver`` code from the `SYNOPSIS`_ nevertheless supports
  streaming by removing any incomplete ETags generated by this vmod.

* By design, ETags generated by this vmod can not be used for backend
  conditional requests.

  The VCL template in the `SYNOPSIS`_ thus contains code to remove any
  conditional request headers based on ``vetag`` ETags.

Implementation note:

* Varnish core code does not officially support modifying headers of
  cache objects after creation, which is exactly what is required
  here. This vmod thus works by leaving a fixed length placeholder
  ETag header with the cache object, which later gets overwritten by
  the VFP. This may or may not work with custom storage engines.

INSTALLING
==========

This vmod is supported for varnish 7.1 and later.

Branches exist for older versions.

Building from source
--------------------

This VMOD is using the standard build procedure.


Quick start
-----------

This sequence should be enough in typical setups:

1. ``./bootstrap``
2. ``make``
3. ``make check`` (regression tests)
4. ``make install`` (may require root: sudo make install)

Alternative configs
-------------------

If you have installed Varnish to a non-standard directory, call
``autogen.sh`` and ``configure`` with ``PKG_CONFIG_PATH`` pointing to
the appropriate path. For example, when varnishd configure was called
with ``--prefix=$PREFIX``, use::

  PKG_CONFIG_PATH=${PREFIX}/lib/pkgconfig
  ACLOCAL_PATH=${PREFIX}/share/aclocal
  export PKG_CONFIG_PATH ACLOCAL_PATH

SYNOPSIS
========

::

        import etag;

        sub vetag_backend_fetch {
            if (bereq.http.If-None-Match ~ {"^(W/)?"vetag"}) {
                unset bereq.http.If-None-Match;
            }
            if (bereq.http.If-Match ~ {"^(W/)?"vetag"}) {
                unset bereq.http.If-Match;
            }
            if (bereq.http.If-Range ~ {"^(W/)?"vetag"}) {
                unset bereq.http.If-Range;
            }
        }

        sub vetag_backend_response {
            if (! beresp.http.ETag) {
                set beresp.filters = beresp.filters + " etag";
                # no Etag for cache miss with streaming
                set beresp.do_stream = false;
                # berep.do_* variables have no effect beyond this point
            }
        }

        sub vetag_deliver {
            # safeguard for do_stream == true
            if (resp.http.Etag ~ {"^(W/)?"vetag.*[-A-Z ]"}) {
                unset resp.http.Etag;
            }
        }

        sub vcl_backend_fetch {
            # first
            call vetag_backend_fetch;
        }

        sub vcl_backend_response {
            # last - or after any change to beresp.do_*
            call vetag_backend_response;
        }

        sub vcl_deliver {
            # first
            call vetag_deliver;
        }

SEE ALSO
========
* :ref:`vcl(7)`
* :ref:`varnishd(1)`

COPYRIGHT
=========

::

  Copyright 2017,2019 UPLEX Nils Goroll Systemoptimierung
  All rights reserved.
 
  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions
  are met:
  1. Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in the
     documentation and/or other materials provided with the distribution.
 
  THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
  FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  SUCH DAMAGE.