# The Varnish Users Guide

The Varnish documentation consists of three main documents:

- The Varnish Tutorial explains the basics and gets you started with Varnish.

- The Varnish Users Guide (this document), explains how Varnish works and how you can use it to improve your website.

- The Varnish Reference Manual contains hard facts and is useful for looking up specific questions.

After The Big Varnish Picture, this Users Guide is organized in sections following the major interfaces to Varnish as a service:

Starting and running Varnish is about getting Varnish configured, with respect to storage, sockets, security and how you can control and communicate with Varnish once it is running.

VCL - Varnish Configuration Language is about getting Varnish to handle the HTTP requests the way you want, what to cache, how to cache it, modifying HTTP headers etc. etc.

Reporting and statistics explains how you can monitor what Varnish does, from a transactional level to aggregating statistics.

Varnish and Website Performance is about tuning your website with Varnish.

Troubleshooting Varnish is for locating and fixing common issues with Varnish.

- The Big Varnish Picture
- Starting and running Varnish
  - Security first
  - Required command line arguments
  - CLI - bossing Varnish around
  - Storage backends
  - Transient Storage
  - Parameters
  - Sizing your cache
- VCL - Varnish Configuration Language
  - VCL Syntax
  - Built-in VCL
  - Request and response VCL objects
  - Backend servers
  - The “none” backend
  - Multiple backends
  - Backends and virtual hosts in Varnish
  - Connecting Through a Proxy
  - Directors
  - Health checks
  - Layering
  - Director Resolution
  - Connection Pooling
  - Hashing
  - Grace mode and keep
  - Separate VCL files
  - Using inline C to extend Varnish
  - VCL Examples
  - Device detection
- Reporting and statistics
  - Logging in Varnish
  - Statistics
- Varnish and Website Performance
  - Achieving a high hitrate
  - The role of HTTP Headers
  - HTTP Vary
  - Cache misses
  - Uncacheable content
  - Purging and banning
  - Compression
- Content composition with Edge Side Includes
  - Example: esi:include
  - Example: esi:remove and <!–esi … –>
  - What happens when it fails ?
  - Can an ESI fragment also use ESI-includes ?
  - Doing ESI on JSON and other non-XML’ish content
  - Ignoring BOM in ESI objects
  - ESI on invalid XML
  - ESI includes with HTTPS protocol
  - ESI on partial responses (206)
  - ESI and return(vcl(…))
  - ESI and gzip compression
- Troubleshooting Varnish
  - When Varnish won’t start
  - Varnish is crashing - panics
  - Varnish is crashing - stack overflows
  - Varnish is crashing - segfaults
  - Varnish gives me Guru meditation
  - Varnish doesn’t cache