Skip to content

V
varnishevent3
Commit f7190396 authored by Tollef Fog Heen's avatar Tollef Fog Heen
Browse files
Options

Add HTML version of getting started guide 

Thanks to cby for fixing this up and HTMLising it.


git-svn-id: http://www.varnish-cache.org/svn/trunk/varnish-cache@3304 d4fa192b-c00b-0410-8231-f00ffab90ce4
parent dc8d6266
Hide whitespace changes
Inline Side-by-side
Showing with 511 additions and 1 deletion
doc/Makefile.am
View file @ f7190396
......@@ -18,7 +18,8 @@ XML = \
all: ${CHANGELOGS}
EXTRA_DIST = ${CHANGELOGS} ${XML} \
changes.css changes-html.xsl
changes.css changes-html.xsl \
getting-started.html
CLEANFILES = ${CHANGELOGS}
......
doc/getting-started.html 0 → 100644
View file @ f7190396
<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 &lt;hostname_or_ip&gt</td>
</tr>
<tr>
<td>—</td>
<td>—</td>
<td> -b '&lt;hostname_or_ip&gt;:&lt;port_or_service&gt;'</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,&lt;buckets&gt;</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,&lt;dir_or_file&gt;</td>
</tr>
<tr>
<td>—</td>
<td>—</td>
<td> -s file,&lt;dir_or_file&gt;,&lt;size&gt;</td>
</tr>
<tr>
<td>—</td>
<td>—</td>
<td> -s file,&lt;dir_or_file&gt;,%lt;size&gt;,&lt;granularity&gt;</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 &lt;fixed_count&gt;</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>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment