]> err.no Git - varnish/commitdiff
Add HTML version of getting started guide
authortfheen <tfheen@d4fa192b-c00b-0410-8231-f00ffab90ce4>
Wed, 15 Oct 2008 18:36:33 +0000 (18:36 +0000)
committertfheen <tfheen@d4fa192b-c00b-0410-8231-f00ffab90ce4>
Wed, 15 Oct 2008 18:36:33 +0000 (18:36 +0000)
Thanks to cby for fixing this up and HTMLising it.

git-svn-id: svn+ssh://projects.linpro.no/svn/varnish/trunk@3304 d4fa192b-c00b-0410-8231-f00ffab90ce4

varnish-cache/doc/Makefile.am
varnish-cache/doc/getting-started.html [new file with mode: 0644]

index 0bad0b7ab5c7431cfe3202c11afd07e49300688b..19df6c37c6d70dad259ec32e87df1c5e613db5aa 100644 (file)
@@ -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}
 
diff --git a/varnish-cache/doc/getting-started.html b/varnish-cache/doc/getting-started.html
new file mode 100644 (file)
index 0000000..cfa0b8d
--- /dev/null
@@ -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 &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>