--- /dev/null
+<?xml version="1.0" encoding="utf-8"?>
+<?xml-stylesheet type="text/css" href="../../share/docbook-xml.css"?>
+<!DOCTYPE article
+ PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<article lang="en">
+ <articleinfo>
+ <releaseinfo role="cvs">$Id$</releaseinfo>
+ <title>Varnish HTTP Accelerator Draft Specification</title>
+ </articleinfo>
+
+ <section>
+ <title>Introduction</title>
+
+ <section>
+ <title>Overview</title>
+
+ <para>Varnish is a high-performance HTTP accelerator.</para>
+
+ <para>XXX</para>
+ </section>
+
+ <section>
+ <title>Terminology</title>
+
+ <para>The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”,
+ “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and
+ “OPTIONAL” in this document are to be interpreted as described
+ in <xref linkend="RFC2119"/>.</para>
+
+ <para>XXX at this time, the above is incorrect because we
+ started out using MoSCoW prioritisation before realising it was
+ inadequate for the task.</para>
+ </section>
+
+ <section>
+ <title>To do</title>
+
+ <para>Use consistent terminology throughout the document (see
+ previous section)</para>
+
+ <para>Clarify the following terms: configuration facility;
+ logging and statistics facility (split in two?); monitoring and
+ tuning facility (split in two? does this overlap with
+ configuration facility?)</para>
+ </section>
+ </section>
+
+ <section>
+ <title>General requirements</title>
+
+ <section>
+ <title>License</title>
+
+ <para>XXX two-clause BSD license</para>
+ </section>
+
+ <section>
+ <title>Version control</title>
+
+ <para>All source code and documentation must be kept under
+ version control in a publicly accessible repository.</para>
+ </section>
+
+ <section>
+ <title>Software platform</title>
+
+ <para>Varnish must be fully functional on the platforms listed
+ in this section.</para>
+
+ <para>Varnish should also be fully functional on other
+ POSIX-derived platforms, insofar as this does not require
+ unreasonable effort.</para>
+
+ <section>
+ <title>FreeBSD</title>
+
+ <para>Varnish must be fully functional on FreeBSD 6.0 or later
+ officially supported releases, including security and errata
+ branches.</para>
+
+ <para>The reference platform for FreeBSD compatibility is
+ FreeBSD 6.1-RELEASE.</para>
+ </section>
+
+ <section>
+ <title>GNU/Linux</title>
+
+ <para>Varnish must be fully functional on GNU/Linux systems
+ with Linux 2.6.12 or later and GNU libc 2.3.2 or later.</para>
+
+ <para>The reference platform for GNU/Linux compatibility is
+ Ubuntu 5.10 “Breezy Badger”.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Hardware platform</title>
+
+ <para>Varnish must be fully functional on both 32-bit and 64-bit
+ Intel-compatible hardware, but may place different limits on
+ operating parameters (such as cache size) depending on the
+ platform and the amount of physical and / or virtual memory
+ available. Varnish must support and take advantage of multiple
+ CPUs or CPU cores if present.</para>
+
+ <para>The reference hardware platform is a dual-CPU AMD Opteron
+ system with 4 GB of RAM divided evenly between the CPUs.</para>
+ </section>
+
+ <section>
+ <title>Language</title>
+
+ <para>Varnish must be implemented in C with as few compiler- and
+ platform-specific extensions as possible.</para>
+ </section>
+
+ <section>
+ <title>Compiler and toolchain</title>
+
+ <para>Varnish must be compilable with the GNU C compiler (GCC)
+ 3.3.5 or later and toolchain (binutils) 2.15 or later.</para>
+
+ <para>Alternative compilers and toolchains should be supported
+ insofar as this does not require unreasonable effort.</para>
+ </section>
+
+ <section>
+ <title>Compile-time configuration</title>
+
+ <para>Varnish must use the GNU Autotools for compile-time
+ configuration. The Makefile templates must be written to work
+ with any POSIX-compliant make(1) utility.</para>
+ </section>
+
+ <section>
+ <title>Third-party dependencies</title>
+
+ <para>Varnish must not depend on any third-party packages other
+ than the compiler, toolchain and configuration tools.</para>
+ </section>
+
+ <section>
+ <title>Incidental tools</title>
+
+ <para>Varnish may be accompanied by incidental tools for
+ purposes such as creating or editing configuration files,
+ warming up the cache, manipulating or generating source code,
+ etc. Insofar as these tools are not required at compilation or
+ installation time nor for the daily operation of Varnish, they
+ may be written in Perl 5.8 or later, and depend on third-party
+ Perl modules available from CPAN.</para>
+ </section>
+
+ <section>
+ <title>Coding standards</title>
+
+ <para>All C source code must conform to the FreeBSD style(9)
+ coding standard.</para>
+ </section>
+
+ <section>
+ <title>Documentation</title>
+
+ <para>Varnish must be accompanied by complete internal and
+ external documentation.</para>
+
+ <para>All documentation must be in English.</para>
+
+ <para>All documentation must be made available online in HTML
+ form, and may be made available online in additional formats
+ such as PDF.</para>
+
+ <section>
+ <title>Internal documentation</title>
+
+ <para>The internal documentation consists of:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Code comments.</para>
+ </listitem>
+ <listitem>
+ <para>Manual pages describing Varnish internals.</para>
+ </listitem>
+ <listitem>
+ <para>Version control history.</para>
+ </listitem>
+ <listitem>
+ <para>Requirements and specification in DocBook XML
+ format.</para>
+ </listitem>
+ <listitem>
+ <para>System architecture in DocBook XML format.</para>
+ </listitem>
+ <listitem>
+ <para>Developer guidelines and other incidental
+ documentation either in the project Wiki or in DocBook XML
+ format.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>External documentation</title>
+
+ <para>The external documentation consists of:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Manual pages for all daemons and command-line
+ tools.</para>
+ </listitem>
+ <listitem>
+ <para>Installation instructions in DocBook XML
+ format.</para>
+ </listitem>
+ <listitem>
+ <para>Administrator's handbook in DocBook XML
+ format.</para>
+ </listitem>
+ <listitem>
+ <para>Sample configuration files.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>Functional requirements</title>
+
+ <section>
+ <title>Functional description</title>
+
+ <para>Varnish accepts HTTP requests from clients and satisfy
+ them with documents retrieved from its cache (disk- and / or
+ memory-based). Documents which are not present in the cache
+ must be retrieved from a set of preconfigured content servers.
+ Requests for documents from other servers than the preconfigured
+ content servers are ignored.</para>
+ </section>
+
+ <section>
+ <title>Protocol support</title>
+
+ <section>
+ <title>HTTP</title>
+
+ <para>Varnish must be able to accept HTTP/1.0 and HTTP/1.1
+ requests from both IPv4 and IPv6 clients.</para>
+
+ <para>Varnish must, in general terms, handle these requests in
+ conformance with <xref linkend="RFC2616"/>.</para>
+
+ <para>Varnish may handle HTTP/0.9 requests in any way it sees
+ fit, including but not limited to returning a 400 Bad Request
+ response or simply closing the connection.</para>
+
+ <para>Varnish must use HTTP/1.1 in its communications with the
+ content servers.</para>
+
+ <para>Varnish may deviate from <xref linkend="RFC2616"/> when
+ this is necessary for interoperability with non-conforming
+ clients or content servers.</para>
+
+ <para>Varnish may deviate from <xref linkend="RFC2616"/> in
+ cases where doing so provides a considerable performance
+ advantage without causing significant harm to
+ interoperability. Any such deviation must be
+ documented.</para>
+
+ <para>In its communications with clients, Varnish must
+ interpret <xref linkend="RFC2616"/> as if it were an origin
+ server. In its communications with content servers, Varnish
+ must interpret <xref linkend="RFC2616"/> as if it were a
+ cache.</para>
+ </section>
+
+ <section>
+ <title>ICP</title>
+
+ <para>Varnish may support ICP for inter-cache coordination.
+ ICP support may be a compile-time option.</para>
+ </section>
+
+ <section>
+ <title>HTCP</title>
+
+ <para>Varnish may support HTCP for inter-cache coordination.
+ HTCP support may be a compile-time option.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Content manipulation</title>
+
+ <para>Varnish won't implement content manipulation at this
+ time.</para>
+
+ <para>Varnish should be designed in such a manner as to make it
+ possible to implement various kinds of content manipulation
+ (such as ESI) at a future date.</para>
+
+ <para>XXX ICAP may be worth looking into (but is probably a
+ performance killer)</para>
+ </section>
+
+ <section>
+ <title>Caching</title>
+
+ <para>Varnish must maintain a local cache of the documets
+ present on the content server.</para>
+
+ <section>
+ <title>Cached set</title>
+
+ <para>If the amount of memory and / or disk available to
+ Varnish is not sufficient to cache the entire document set,
+ Varnish must attempt to identify a subset to cache which
+ minimizes load on the content servers.</para>
+
+ <para>Varnish should offer multiple alternative cache control
+ algorithms. At the very least, the LRU (least-recently-used)
+ and WLRU (LRU weighted by document size) algorithms should be
+ implemented.</para>
+ </section>
+
+ <section>
+ <title>Cacheability</title>
+
+ <para>A request which includes authentication headers must not
+ be served from cache.</para>
+
+ <para>Varnish must interpret Cache-Control directives received
+ from content servers as follows:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>public: the document will be cached even if
+ authentication headers are present.</para>
+ </listitem>
+ <listitem>
+ <para>private: the document will not be cached, since
+ Varnish is a shared cache.</para>
+ </listitem>
+ <listitem>
+ <para>no-cache: the document will not be cached.</para>
+ </listitem>
+ <listitem>
+ <para>no-store: XXX</para>
+ </listitem>
+ <listitem>
+ <para>s-maxage: overrides max-age, since Varnish is a
+ shared cache.</para>
+ </listitem>
+ <listitem>
+ <para>max-age: overrides the Expires header.</para>
+ </listitem>
+ <listitem>
+ <para>min-fresh: ignored.</para>
+ </listitem>
+ <listitem>
+ <para>max-stale: ignored.</para>
+ </listitem>
+ <listitem>
+ <para>only-if-cached: ignored.</para>
+ </listitem>
+ <listitem>
+ <para>must-revalidate: as specified in <xref
+ linkend="RFC2616"/> §14.9.4.</para>
+ </listitem>
+ <listitem>
+ <para>proxy-revalidate: as must-revalidate.</para>
+ </listitem>
+ <listitem>
+ <para>no-transform: ignored.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Varnish must ignore Cache-Control directives received
+ from clients.</para>
+ </section>
+
+ <section>
+ <title>Expiry</title>
+
+ <para>If a content server returns a document with a s-maxage
+ directive, Varnish will set the expiry time for that document
+ to the time of the request plus the number of seconds
+ specified by the directive.</para>
+
+ <para>If a content server returns a document with no s-maxage
+ directive but a max-age directive, Varnish will set the expiry
+ time for that document to the time of the request plus the
+ number of seconds specified by the max-age directive.</para>
+
+ <para>If a content server returns a document with no s-maxage
+ or max-age directive but an Expires header, Varnish must set
+ the expiry time for that document to the value specified by
+ the Expires header.</para>
+
+ <para>When sending a document to a client, Varnish must set
+ the Expires header to the document's expiry time.</para>
+ </section>
+
+ <section>
+ <title>Refreshing</title>
+
+ <para>Varnish must attempt to refresh documents before they
+ expire, in order to avoid stalling a client request while
+ retrieving an expired document.</para>
+
+ <para>XXX</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Management</title>
+
+ <section>
+ <title>Management interface</title>
+
+ <para>Varnish must provide an interface for external
+ management utilities. This interface must accept connections
+ on a Unix socket and / or a TCP socket, depending on
+ configuration.</para>
+
+ <para>Varnish may assume that the management interface is
+ adequately protected by socket permissions or firewall rules,
+ as applicable, and that any data it receives through this
+ interface is valid management data from an authorized
+ administrator.</para>
+
+ <para>Varnish may further assume that all data received
+ through the management interface is well-formed and
+ meaningful.</para>
+ </section>
+
+ <section>
+ <title>Management library</title>
+
+ <para>Varnish must be accompanied by a C library, hereafter
+ referred to as the management library, which provides a
+ reasonably high-level API to the management interface</para>
+
+ <para>Varnish should be accompanied by a Perl library which
+ provides Perl bindings to the management library.</para>
+
+ <para>Varnish may be accompanied by libraries which provide
+ appropriate bindings to the management library for other
+ programming or scripting languages.</para>
+ </section>
+
+ <section>
+ <title>CLI management tool</title>
+
+ <para>Varnish must be accompanied by a CLI management tool,
+ written in C, which serves as a front-end to the management
+ library.</para>
+
+ <para>The CLI management tool must allow management commands
+ to be passed on the command line.</para>
+
+ <para>In addition, the CLI management tool should offer an
+ interactive mode using libreadline, libedit or a similar
+ line-editing library.</para>
+ </section>
+
+ <section>
+ <title>Web-based management tool</title>
+
+ <para>Varnish should be accompanied by a web-based management
+ tool. This tool should have the ability to generate graphs
+ and histograms based on the data described in <xref
+ linkend="sect.logging-statistics"/>.</para>
+ </section>
+
+ <section>
+ <title>Plugins for third-party tools</title>
+
+ <para>Varnish may be accompanied by plugins for third-party
+ management tools such as Munin, Nagios and NAV.</para>
+ </section>
+
+ <section>
+ <title>Configuration</title>
+
+ <para>XXX</para>
+ </section>
+
+ <section id="sect.logging-statistics">
+ <title>Logging and statistics</title>
+
+ <para>A separate application is responsible for collecting,
+ collating and analyzing log data which Varnish makes available
+ in circular shared memory buffers.</para>
+
+ <para>Varnish must provide the data necessary to compute
+ lifetime totals and sliding averages for the following:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Total size of documents served to clients</para>
+ </listitem>
+ <listitem>
+ <para>Total size of data transmitted to clients, including
+ headers, error messages, etc.</para>
+ </listitem>
+ <listitem>
+ <para>Total size of data received from clients, including
+ request headers etc.</para>
+ </listitem>
+ <listitem>
+ <para>Number of client connections received</para>
+ </listitem>
+ <listitem>
+ <para>Number of client requests served</para>
+ </listitem>
+ <listitem>
+ <para>Client requests broken down by result code</para>
+ </listitem>
+ <listitem>
+ <para>Total size of documents retrieved from content
+ servers</para>
+ </listitem>
+ <listitem>
+ <para>Total size of data received from content servers,
+ including headers, error messages, etc.</para>
+ </listitem>
+ <listitem>
+ <para>Total size of data sent to content servers,
+ including request headers etc.</para>
+ </listitem>
+ <listitem>
+ <para>Number of content server connections
+ initiated</para>
+ </listitem>
+ <listitem>
+ <para>Number of content server requests sent</para>
+ </listitem>
+ <listitem>
+ <para>Content server requests broken down by result
+ code</para>
+ </listitem>
+ <listitem>
+ <para>Cache effectiveness as the ratio of bytes served to
+ clients to bytes requested from content servers</para>
+ </listitem>
+ <listitem>
+ <para>Cache effectiveness as the ratio of client requests
+ to content server requests</para>
+ </listitem>
+ <listitem>
+ <para>Number of active server processes / threads, broken
+ down by process / thread type</para>
+ </listitem>
+ <listitem>
+ <para>XXX length of request queues</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In addition, Varnish must provide the data necessary to
+ compute the average, median and distribution for the
+ following:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Size of documents served, per unique document</para>
+ </listitem>
+ <listitem>
+ <para>Size of documents served, per request</para>
+ </listitem>
+ <listitem>
+ <para>Client connection duration</para>
+ </listitem>
+ <listitem>
+ <para>Requests per client connection</para>
+ </listitem>
+ <listitem>
+ <para>Client request completion time, broken down by
+ request type (HEAD / GET), cache status (HIT / MISS) and
+ outcome (200, 404...)</para>
+ </listitem>
+ <listitem>
+ <para>Content server connection duration</para>
+ </listitem>
+ <listitem>
+ <para>Requests per content server connection</para>
+ </listitem>
+ <listitem>
+ <para>Content server request completion time, broken down
+ by request type (HEAD / GET) and outcome (200,
+ 404...)</para>
+ </listitem>
+ <listitem>
+ <para>XXX time spent in request queues</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+
+ <section>
+ <title>Run-time monitoring and tuning</title>
+
+ <para>Varnish must provide low-level monitoring and tuning
+ facilities. A separate application is responsible for providing
+ a user-friendly interface to these facilities.</para>
+
+ <para>The following monitoring operations must be
+ supported:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Cache status of individual documents</para>
+ </listitem>
+ <listitem>
+ <para>Cache status of documents matching a glob or regular
+ expression</para>
+ </listitem>
+ <listitem>
+ <para>Access statistics of individual documents</para>
+ </listitem>
+ <listitem>
+ <para>Access statistics of documents matching a glob or
+ regular expression</para>
+ </listitem>
+ <listitem>
+ <para>XXX</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The following tuning operations must be supported:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Forced invalidation of individual documents</para>
+ </listitem>
+ <listitem>
+ <para>Forced invalidation of documents matching a glob or regular expression</para>
+ </listitem>
+ <listitem>
+ <para>XXX</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Clustering</title>
+
+ <para>Clustering is defined in this context as a situation where
+ multiple servers are set up to run Varnish with the same
+ configuration, serving data from the same content servers to the
+ same set of clients.</para>
+
+ <section>
+ <title>Management</title>
+
+ <para>Varnish must be accompanied by a multiplexer for the
+ management interface which provide a single point of access to
+ the entire cluster for management tools such as the CLI
+ management tool or a web-based management interface.</para>
+
+ <para>The management protocol must be designed to allow
+ management commands to be targeted at individual nodes. The
+ default behaviour must be to propagate management commands to
+ all nodes in the cluster.</para>
+ </section>
+
+ <section>
+ <title>Configuration</title>
+
+ <para>When multiple Varnish servers act together as a cluster,
+ the configuration facility is responsible for ensuring that
+ all nodes share the same configuration and that configuration
+ changes are applied to all nodes in a timely fashion.</para>
+ </section>
+
+ <section>
+ <title>Logging and statistics</title>
+
+ <para>When multiple Varnish servers act together as a cluster,
+ the logging and statistics facilities must base its reports on
+ aggregated data as if the cluster were a single Varnish
+ server.</para>
+
+ <para>Per-node data may optionally be made available in
+ addition to aggregated data.</para>
+ </section>
+
+ <section>
+ <title>Run-time monitoring and tuning</title>
+
+ <para>When multiple Varnish servers act together as a cluster,
+ the run-time monitoring and tuning facilities must propagate
+ invalidation requests and other administrative commands to all
+ servers in the cluster.</para>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>Application structure</title>
+
+ <section>
+ <title>Components</title>
+
+ <para>This section lists the major components in Varnish.</para>
+
+ <section>
+ <title>Listener</title>
+
+ <para>The Listener monitors the listening socket and accepts
+ incoming client connections. Once the connection is
+ established, it is passed to the Accepter.</para>
+
+ <para>The Listener should take advantage of accept filters or
+ similar technologies on systems where they are
+ available.</para>
+ </section>
+
+ <section>
+ <title>Accepter</title>
+
+ <para>The Accepter reads an HTTP request from a client
+ connection. It parses the request line and header only to the
+ extent necessary to establish well-formedness and determine
+ the requested URL.</para>
+
+ <para>The Accepter then queries the Keeper about the status of
+ the requested document (identified by its full URL). If the
+ document is present and valid in the cache, the request is
+ passed directly to a Sender. Otherwise, it is passed to a
+ Retriever queue.</para>
+ </section>
+
+ <section>
+ <title>Keeper</title>
+
+ <para>The Keeper manages the document cache. XXX</para>
+ </section>
+
+ <section>
+ <title>Sender</title>
+
+ <para>The Sender transfers the contents of the requested
+ document to the client. It examines the HTTP request header
+ to determine the correct way in which to do this – Range,
+ If-Modified-Since, Content-Encoding and other options may
+ affect the type and amount of data transferred.</para>
+
+ <para>There may be multiple concurrent Sender threads.</para>
+ </section>
+
+ <section>
+ <title>Retriever</title>
+
+ <para>The Retriever is responsible for retrieving documents
+ from the content servers. It is triggered either by an
+ Accepter trying to satisfy a request for a document which is
+ not in the cache, or by the Janitor when a “hot” document is
+ nearing expiry. Either way, there may be a queue of requests
+ waiting for the document to arrive; when it does, the
+ Retriever passes those requests to a Sender.</para>
+
+ <para>There may be multiple concurrent Retriever
+ threads.</para>
+ </section>
+
+ <section>
+ <title>Janitor</title>
+
+ <para>The Janitor keeps track of the expiry time of cached
+ documents and attempts to retrieve fresh copies of documents
+ which are soon to expire.</para>
+ </section>
+
+ <section>
+ <title>Logger</title>
+
+ <para>The Logger keeps logs of various types of events in
+ circular shared-memory buffers. These buffers must be managed
+ using either POSIX shared memory primitives or file-backed
+ mmap(2).</para>
+
+ <para>It is the responsibility of each module to feed relevant
+ log data to the Logger.</para>
+ </section>
+ </section>
+ </section>
+
+ <bibliography>
+ <title>References</title>
+
+ <bibliomixed id="RFC2119"/>
+ <bibliomixed id="RFC2186"/>
+ <bibliomixed id="RFC2616"/>
+ <bibliomixed id="RFC2756"/>
+ <bibliomixed id="RFC3507"/>
+ </bibliography>
+</article>