<article lang="en">
<articleinfo>
<releaseinfo role="cvs">$Id$</releaseinfo>
- <title>Varnish HTTP Accelerator Draft Specification</title>
+ <title>Varnish HTTP Accelerator Architecture</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>
<bibliography>
<title>References</title>
- <bibliomixed id="RFC2119"/>
- <bibliomixed id="RFC2186"/>
<bibliomixed id="RFC2616"/>
- <bibliomixed id="RFC2756"/>
- <bibliomixed id="RFC3507"/>
</bibliography>
</article>
projects / varnish / commitdiff