Varnish and reverse proxies #

This page is for system administrators at hosting companies who run a reverse proxy, a caching proxy such as Varnish, or a load balancer in front of customer sites. It answers: whether Exponential needs one at all, what the proxy must send and be trusted for, what a caching proxy may store, and how to purge it. Varnish's own configuration language is not described here; check its documentation. The sources are Chapter 8, section 8.8, Forwarded headers are trusted only from configured proxies and Chapter 15, section 15.14.

Contents #

1. Do you need a proxy?
2. What the proxy must send
3. Trusting the proxy
4. A caching proxy: what may be stored
5. Purging: Exponential sends none
6. Checks and symptoms
7. Checklist

Do you need a proxy? #

For sites migrated from older platforms that used Varnish, the installation book says: "Either drop Varnish (the HTTP cache or Velocity's response cache does the same job inside Exponential), or let it cache anonymous pages for a short time only ..., or purge it yourself."

What the proxy must send #

Derived examples for nginx and Apache in front of Velocity are on Velocity beside Apache or nginx.

Trusting the proxy #

Forwarded headers count only from a trusted peer. There are two lists:

A proxy on the same machine (including Varnish on loopback) is covered. A proxy elsewhere must be listed:

# settings/override/site.ini.append.php
[HTTPHeaderSettings]
TrustedProxies[]
TrustedProxies[]=127.0.0.1
TrustedProxies[]=::1
TrustedProxies[]=10.0.0.0/16
ClientIpByCustomHTTPHeader=X-Forwarded-For

• Entries are addresses or ranges, IPv4 and IPv6; host names are not resolved. An override that starts with TrustedProxies[] on its own line replaces the list.
• Comments go on lines of their own: after a value a # is read as part of the value and the entry is ignored.
• ClientIpByCustomHTTPHeader is needed under PHP-FPM only; under Velocity the engine hands the visitor's address over as REMOTE_ADDR.
• Trusting a proxy means trusting it to set the headers. A local proxy that passes on a visitor's own X-Forwarded-Proto would carry it through; if you cannot change such a proxy, set TrustedProxies[] empty.
• Make sure the origin cannot be reached around the proxy (firewall, security group).

For Velocity, put the list in a snippet such as /etc/vc/conf-available/reverse-proxy.conf and enable it with exp:velocity conf enable reverse-proxy (Velocity beside Apache or nginx). Engine 0.0.4.44 or later is needed for the forwarded protocol to be read only from trusted proxies.

A caching proxy: what may be stored #

What Exponential gives a proxy to work with:

• Pages are no-cache by default. To let a proxy store anonymous pages, switch on [HTTPHeaderSettings] with OnlyForAnonymous=enabled and a short max-age (HTTP cache headers).
• Pages that carry a form token are sent private.
• The session cookie's name follows site.ini [Session] SessionNameHandler: with default PHP names it; with custom it is SessionNamePrefix (shipped eZSESSID) plus a per-siteaccess digest. The kernel also sets is_logged_in for signed-in visitors. A proxy rule that bypasses the cache on either cookie matches what Velocity's own response cache does.
• Static files carry long lifetimes under Velocity (StaticMaxAge) and can be cached freely.

Purging: Exponential sends none #

Exponential sends no purge or ban requests to a proxy; there is no PURGE or BAN in the kernel. A proxy that keeps pages longer than their max-age will serve stale pages after an edit. Options from the installation book:

1. Short lifetimes only: let the proxy keep anonymous pages for the max-age you configured, and nothing longer.
2. Purge by tag: httpcache.ini [HttpCacheSettings] TagHeader=xkey names each page's purge tags in a header for the Varnish xkey module (Surrogate-Key for Fastly, Cache-Tag for Cloudflare). The setting and the tags belong to the role-aware HTTP cache (HTTP cache); test that pages carry them.
3. Purge on publish yourself: the kernel emits content/cache with the node and object ids on every publish (kernel/classes/ezcontentcachemanager.php), which a listener in site.ini [Event] Listeners[] can turn into purges.
4. Drop the proxy cache and use Velocity's response cache or the HTTP cache, which purge themselves.

Checks and symptoms #

With the site reachable directly, a forwarded header from a visitor must change nothing:

curl -s -o /dev/null -w '%{redirect_url}\n' -H 'X-Forwarded-Proto: https' http://example.com/user/logout
# expected: http://example.com/   -- https:// here means the header was believed

Checklist #

• To do: The proxy sets X-Forwarded-Proto and appends or sets X-Forwarded-For; passes Host.
• To do: The proxy is trusted (TrustedProxies[], or Q.webserver.proxy.trusted for Velocity); the origin is not reachable around it.
• To do: The curl check passes directly and through the proxy.
• To do: A caching proxy bypasses requests with the session cookie or is_logged_in, and stores only public pages.
• To do: A purge strategy is chosen and written into the plan.

Related pages #

• Velocity beside Apache or nginx
• HTTP cache headers
• CDN
• Forwarded headers are trusted only from configured proxies
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.