r3304 - trunk/varnish-cache/doc
tfheen at projects.linpro.no
tfheen at projects.linpro.no
Wed Oct 15 20:36:33 CEST 2008
Author: tfheen
Date: 2008-10-15 20:36:33 +0200 (Wed, 15 Oct 2008)
New Revision: 3304
Added:
trunk/varnish-cache/doc/getting-started.html
Modified:
trunk/varnish-cache/doc/Makefile.am
Log:
Add HTML version of getting started guide
Thanks to cby for fixing this up and HTMLising it.
Modified: trunk/varnish-cache/doc/Makefile.am
===================================================================
--- trunk/varnish-cache/doc/Makefile.am 2008-10-15 18:36:29 UTC (rev 3303)
+++ trunk/varnish-cache/doc/Makefile.am 2008-10-15 18:36:33 UTC (rev 3304)
@@ -18,7 +18,8 @@
all: ${CHANGELOGS}
EXTRA_DIST = ${CHANGELOGS} ${XML} \
- changes.css changes-html.xsl
+ changes.css changes-html.xsl \
+ getting-started.html
CLEANFILES = ${CHANGELOGS}
Added: trunk/varnish-cache/doc/getting-started.html
===================================================================
--- trunk/varnish-cache/doc/getting-started.html (rev 0)
+++ trunk/varnish-cache/doc/getting-started.html 2008-10-15 18:36:33 UTC (rev 3304)
@@ -0,0 +1,509 @@
+<h1>Getting started with Varnish 2.0</h1>
+
+<h2>Welcome!</h2>
+
+<p>Welcome to the wonders of Varnish 2.0. Hopefully you will be up and
+running in no-time after a quick walkthrough of this document. </p>
+
+<h2>Installing Varnish</h2>
+
+<p>You can download Varnish packages for the major Linux
+distributions, such as Redhat, Suse and Debian from the Varnish
+website. For other Linux distributions, FreeBSD and other supported
+platforms, Varnish must be compiled and installed
+from <a href="http://sourceforge.net/project/showfiles.php?group_id=155816">Sourceforge.</a>.
+
+<p>The sample installation in this walkthrough is based on a FreeBSD
+installation from source. </p>
+
+<p> For installation instructions on other operating systems, please
+visit the website, where we currently have the following
+available: </p>
+
+<ul>
+<li><a href="http://varnish.projects.linpro.no/wiki/Installation">From source code (FreeBSD, Mac OS X)</a></li>
+<li><a href="http://varnish.projects.linpro.no/wiki/VarnishOnRedhat">Redhat Enterprise Linux / Centos</a></li>
+<li><a href="http://varnish.projects.linpro.no/wiki/VarnishOnDebian">Debian GNU/Linux and Ubuntu</a> </li>
+<li><a href="http://varnish.projects.linpro.no/wiki/VarnishOnSuse">SUSE Linux (SLES and OpenSUSE)</a> </li>
+<li><a href="http://varnish.projects.linpro.no/wiki/InstallationOnUbuntuDapper">Ubuntu Dapper</a> </li>
+<li><a href="http://varnish.projects.linpro.no/wiki/GentooEbuild">Gentoo</a></li>
+</ul>
+
+<h2>Prerequisites </h2>
+
+<p>Make sure you have the following accessible when you are installing
+your copy of Varnish.</p>
+
+<ul>
+<li>A working command-line knowledge of your chosen OS </li>
+<li>A recent version of GCC (3.3.x or newer should be fine, 4.2.1 or newer recommended) </li>
+<li>A POSIX-compatible make (GNU make is fine) </li>
+<li>A release tarball from <a href="http://sourceforge.net/project/showfiles.php?group_id=155816">Sourceforge</a></li>
+</ul>
+
+<h2> Installing Varnish from source on FreeBSD </h2>
+
+<p>First , run configure. In most cases, the defaults are correct and you do not need to specify any command-line options, except perhaps—prefix. If you plan on hacking the Varnish sources, however, you will most likely want to turn on stricter error checks and dependency tracking:
+</p>
+<code>$ ./configure --enable-debugging-symbols --enable-developer-warnings --enable-dependency-tracking</code>
+
+<ul>
+
+<li>If you have gcc 4.2.0 or newer,
+ add <code>--enable-extra-warnings</code> to get additional
+ compile-time warnings</li>
+<li>If you have a version of gcc with stack protection,
+ add <code>--enable-stack-protector</code> to enable run-time stack
+ smashing detection</li>
+<li>If you’re trying to track down an elusive bug or a race
+ condition, <code>--enable-diagnostics</code> may help, but it will
+ reduce performance and increase the amount of log data
+ generated</li>
+<li>If configure completes without any errors, simply
+ run <code>make</code> to compile Varnish and <code>make
+ install</code> to install it.</li>
+<li>Start Varnish by typing: <code>varnishd -f
+ /etc/varnish/default.vcl</code></li>
+</ul>
+
+<h2> Configuring your Varnish installation</h2>
+
+<p> The Varnish daemon is configured by using command line options and
+the powerful Varnish Configuration Language (VCL). The location of the
+default VCL configuration file and the command line options varies,
+depending on which platform you have installed Varnish.</p>
+
+<h3>Command line options </h3>
+
+<p>The command line options configure the basics of the Varnish
+daemon, like the listen address and port, which VCL script to use and
+the working directory. The following options can be set:</p>
+
+<table>
+ <tbody><table border = "1"><tr>
+ <th>Command</th>
+ <th>Function</th>
+ <th>Comment</th>
+
+ </tr>
+ <tr>
+ <td>-a address:port </td>
+ <td> HTTP listen address and port</td>
+ <td>—</td>
+
+ </tr>
+ <tr>
+ <td>-b address:port </td>
+ <td> backend address and port</td>
+
+ <td>—</td>
+ </tr>
+ <tr>
+ <td>—</td>
+ <td>—</td>
+
+ <td> -b <hostname_or_ip></td>
+ </tr>
+ <tr>
+ <td>—</td>
+ <td>—</td>
+
+ <td> -b '<hostname_or_ip>:<port_or_service>'</td>
+ </tr>
+ <tr>
+ <td>
+-d </td>
+ <td> debug</td>
+
+ <td>—</td>
+ </tr>
+ <tr>
+ <td>-f file </td>
+ <td> VCL script</td>
+
+ <td>The -f option points to the VCL script to use. If it is omitted, the -b option must be used to define a backend to use with the default configuration.</td>
+ </tr>
+ <tr>
+ <td>-F </td>
+ <td> Run in foreground</td>
+
+ <td>—</td>
+ </tr>
+ <tr>
+ <td>-h kind[,hashoptions] </td>
+ <td> Hash specification</td>
+
+ <td>—</td>
+ </tr>
+ <tr>
+ <td>—</td>
+ <td>—</td>
+
+ <td> -h simple_list. Do not use – for debug only</td>
+ </tr>
+ <tr>
+ <td>—</td>
+ <td>—</td>
+
+ <td> -h classic [default]</td>
+ </tr>
+ <tr>
+ <td>—</td>
+ <td>—</td>
+
+ <td> -h classic,<buckets></td>
+ </tr>
+ <tr>
+ <td>-l bytesize </td>
+ <td> Size of shared memory log</td>
+
+ <td>—</td>
+ </tr>
+ <tr>
+ <td>-n dir </td>
+ <td> varnishd working directory</td>
+
+ <td>—</td>
+ </tr>
+ <tr>
+ <td>-P file </td>
+ <td> PID file</td>
+
+ <td>—</td>
+ </tr>
+ <tr>
+ <td>-p param=value </td>
+ <td> set parameter</td>
+
+ <td>—</td>
+ </tr>
+ <tr>
+ <td>-s kind[,storageoptions] </td>
+ <td> Backend storage specification</td>
+
+ <td>—</td>
+ </tr>
+ <tr>
+ <td>—</td>
+ <td>—</td>
+
+ <td> -s malloc</td>
+ </tr>
+ <tr>
+ <td>—</td>
+ <td>—</td>
+
+ <td> -s file [default: use /tmp]</td>
+ </tr>
+ <tr>
+ <td>—</td>
+ <td>—</td>
+
+ <td> -s file,<dir_or_file></td>
+ </tr>
+ <tr>
+ <td>—</td>
+ <td>—</td>
+
+ <td> -s file,<dir_or_file>,<size></td>
+ </tr>
+ <tr>
+ <td>—</td>
+ <td>—</td>
+
+ <td> -s file,<dir_or_file>,%lt;size>,<granularity></td>
+ </tr>
+ <tr>
+ <td>-t </td>
+ <td> Default TTL</td>
+
+ <td>—</td>
+ </tr>
+ <tr>
+ <td>-T address:port </td>
+ <td> Telnet listen address and port</td>
+
+ <td>To
+enable the command-line management interface, the -T option must be
+used. This will enable telneting to the defined port to pass commands
+to the running Varnish daemon either using varnishadm or use telnet
+directly to the port to access the command-line interface.</td>
+ </tr>
+ <tr>
+ <td>-V </td>
+ <td> version</td>
+
+ <td>—</td>
+ </tr>
+ <tr>
+ <td>-w int[,int[,int]] </td>
+ <td> Number of worker threads</td>
+
+ <td>—</td>
+ </tr>
+ <tr>
+ <td>—</td>
+ <td>—</td>
+
+ <td> -w <fixed_count></td>
+ </tr>
+ <tr>
+ <td>—</td>
+ <td>—</td>
+
+ <td> -w min,max</td>
+ </tr>
+ <tr>
+ <td>—</td>
+ <td>—</td>
+
+ <td> -w min,max,timeout [default: -w2,500,300]</td>
+ </tr>
+ <tr>
+ <td>-u user</td>
+ <td> Priviledge separation user id</td>
+
+ <td>—</td>
+ </tr>
+ </tbody>
+ <tbody>
+ </tbody>
+</table>
+
+<h2>VCL</h2>
+
+<p>VCL is a small, domain-specific language used to define request
+ handling and document caching policies for the Varnish HTTP
+ accelerator. Some of its features are:</p>
+<ul>
+ <li>Simple syntax, similar to that of Perl and C</li>
+ <li>Access to request-manipulation</li>
+ <li>Regular expressions for matching</li>
+ <li>User defined sub-routines</li>
+ <li>Access control lists</li>
+</ul>
+
+
+<p>The VCL configuration mainly consists of the backend and ACL
+ definitions, in addition to a number of special sub-routines which
+ hook into the Varnish workflow. These sub-routines may inspect and
+ manipulate HTTP headers and various other aspects of each request,
+ and to a certain extent decide how the request should be handled.
+
+<p>The direction in the workflow is determined in each sub-routine by
+ a given keyword.</p>
+
+<strong> </strong><table> <table border = "1">
+ <tbody><tr>
+ <th>Function</th>
+ <th>Description</th>
+ <th>Possible keywords</th>
+ </tr>
+ <tr>
+ <th>vcl_recv</th>
+ <td>Called after receiving a request. Decides how to serve the request</td>
+ <td> error, pass, pipe</td>
+ </tr>
+ <tr>
+ <th>vcl_pipe</th>
+ <td>Called after entering pipe mode.Creates a direct connection between the client and the backend, bypassing Varnish all together.</td>
+ <td> error, pipe</td>
+ </tr>
+ <tr>
+ <th>vcl_pass</th>
+ <td>Called
+after entering pass mode. Unlike pipe mode, only the current request
+bypasses Varnish. Subsequent requests for the same connection are
+handled normally.</td>
+ <td> error, pass</td>
+ </tr>
+ <tr>
+ <th>vcl_hash</th>
+ <td>Called when computing the hash key for an object.</td>
+ <td>hash</td>
+ </tr>
+ <tr>
+ <th>vcl_hit</th>
+ <td>Called after a cache hit.</td>
+ <td>error, pass, deliver</td>
+ </tr>
+ <tr>
+ <th>vcl_miss</th>
+ <td>Called after a cache miss.</td>
+ <td>error, pass, fetch</td>
+ </tr>
+ <tr>
+ <th>vcl_fetch</th>
+ <td>Called
+after a successful retrieval from the backend. An ‘insert’ will add the
+retrieved object in the cache and then continue to vcl_deliver</td>
+ <td>error, pass, insert</td>
+ </tr>
+ <tr>
+ <th>vcl_deliver</th>
+ <td>Called before the cached object is delivered to the client.</td>
+ <td>error, deliver</td>
+ </tr>
+ <tr>
+ <th>vcl_timeout</th>
+ <td>Called
+by the reaper thread shortly before an object expires in the cache
+‘discard’ will discard the object and ‘fetch’ will retrieve a fresh copy</td>
+ <td>discard, fetch</td>
+ </tr>
+ <tr>
+ <th>vcl_discard</th>
+ <td>Called by the reaper thread when a cached object is about to be discarded due to expiration or space is running low</td>
+ <td>discard, keep</td>
+ </tr>
+ </tbody></table>
+
+
+<p>Varnish ships with a default configuration
+( <strong>default.vcl</strong> in /etc/varnish ), so you won’t have to
+define all the subroutines yourself. This default file is set up to
+work straight out of the box after you have defined a backend. Please
+note that default subroutines will be invoked should the custom
+configuration not terminate with a keyword
+
+<h2>Defining a backend and the use of directors</h2>
+
+<p>A backend can either be set by using the -b command line option, or
+by defining it in the VCL configuration file. A backend declaration in
+VCL is defined like this:</p>
+
+<pre>
+backend www {
+ .host = "www.example.com";
+ .port = "http";
+}
+</pre>
+
+<p>The backend object can later be used to select a backend at request time:</p>
+
+<pre>
+if (req.http.host ~ "^example.com$") {
+ set req.backend = www;
+}
+</pre>
+
+<p>If there are several backends delivering the same content, they can
+be grouped together using a director declaration:</p>
+
+<pre>
+director www-director round-robin {
+ { .backend = www; }
+ { .backend = { .host = "www2.example.com"; .port = "http"; } }
+}
+</pre>
+
+<p>A director will choose one of the defined backend depending on its
+policy. A ‘random’ director will choose a random backend, biased by a
+weight for each backend, and a ‘round-robin’ backend will choose a
+backend in a round robin fashion. The director object can be used in
+the same way as the backend object for selecting a backend:</p>
+
+<pre>
+if (req.http.host ~ "^(www.)\.example\.com$") {
+ set req.backend = www-director;
+}
+</pre>
+
+<h3>Access Control Lists </h3>
+
+<p> An Access Control List (ACL) declaration creates and initializes a
+named access control list which can later be used to match client
+addresses: </p>
+
+<pre>
+acl local
+ {
+ "localhost"; /* myself */
+ "192.0.2.0"/24; /* and everyone on the local network */
+ ! "192.0.2.23"; /* except for the dialin router */
+ }
+</pre>
+
+<p>To match an IP address against an ACL, use the match operator:</p>
+<pre>
+if (client.ip ~ local) { pipe; }
+</pre>
+
+<h2>Examples </h2>
+
+As mentioned, Varnish ships ships with a default set of subroutines
+which hook themselves up to what you define.These subroutines will be
+processed subsequently, provided they are not explicitly terminated in
+the custom VCL. Tuning is an important part of implementing a
+cache-solution, and a custom configuration will probably be
+needed. Here are some examples to get you going - also note that
+irc.linpro.no #varnish is a great place to get help and to discuss all
+things Varnish:
+
+<h3>Selecting a backend based on the type of document</h3>
+<p>- this can be done with the regular expression matching operator. </p>
+
+<pre>
+sub vcl_recv {
+ if (req.url ~ "\.(gif|jpg|swf|css|j)$") {
+ unset req.http.cookie;
+ unset req.http.authenticate;
+ set req.backend = b1;
+ } else {
+ set req.backend = b2;
+ }
+}
+</pre>
+
+<h3>h3. Retrying with another backend if one backend reports a non-200 response.</h3>
+<pre>
+sub vcl_recv {
+ if (req.restarts == 0) {
+ set req.backend = b1;
+ } else {
+ set req.backend = b2;
+ }
+}
+
+sub vcl_fetch {
+ if (obj.status != 200) {
+ restart;
+ }
+}
+</pre>
+
+<h3>Preventing search engines from populating the cache with old documents</h3> -
+<p>This can be done by checking the user-agent header in the HTTP request. </p>
+
+<pre>
+sub vcl_miss {
+ if (req.http.user-agent ~ "spider") {
+ error 503 "Not presently in cache";
+ }
+}
+</pre>
+
+<p>For more examples, please visit our wiki at http://www.varnish-cache.org. </p>
+
+<h2>Varnish tools</h2>
+<p>Varnish has a set of command line tools and utilities to monitor and administer Varnish. These are: </p>
+<ul>
+<li>varnishncsa: Displays the varnishd shared memory logs in Apache / NCSA combined log format</li>
+<li> varnishlog: Reads and presents varnishd shared memory logs.</li>
+<li>varnishstat: Displays statistics from a running varnishd instance.</li>
+<li>varnishadm: Sends a command to the running varnishd instance. </li>
+<li>varnishhist: Reads varnishd shared memory logs and presents a continuously updated histogram showing the distribution of the last N requests by their processing. </li>
+<li>varnishtop: Reads varnishd shared memory logs and presents a continuously updated list of the most commonly occurring log entries.</li>
+<li>varnishreplay: Parses varnish logs and attempts to reproduce the traffic.</li>
+ </ul>
+
+<p>For further information and example of usage, please refer to the man-pages. </p>
+
+<h2>Further documentation </h2>
+
+<p>The project web site is a good source for information about
+Varnish, with updated news, mailings lists, how-to's, troubleshooting
+tips, and more. The web site is located
+at <a href="http://www.varnish-cache.org">http://www.varnish-cache.org</a>. For
+on-line reference manual, man-pages exists for both the VCL language
+as well as all the Varnish command line tools.</p>
More information about the varnish-commit
mailing list