[master] 87cad02 rework tutorial according to new layout
Per Buer
perbu at varnish-cache.org
Tue Feb 19 14:43:20 CET 2013
commit 87cad02c2af022be899a622d1b3a26b385d05726
Author: Per Buer <perbu at varnish-software.com>
Date: Tue Feb 19 14:00:03 2013 +0100
rework tutorial according to new layout
diff --git a/doc/sphinx/tutorial/index.rst b/doc/sphinx/tutorial/index.rst
index 6444be9..bd42134 100644
--- a/doc/sphinx/tutorial/index.rst
+++ b/doc/sphinx/tutorial/index.rst
@@ -13,13 +13,12 @@ following points:
Then we hand things over to the user guide.
-Let's start off by including some of the stuff we chucked out of the
-previous tutorial - now "users guide"
+.. Let's start off by including some of the stuff we chucked out of the
+.. previous tutorial - now "users guide"
.. toctree:: :maxdepth: 1
introduction
- web_accelerator
starting_varnish
putting_varnish_on_port_80
backend_servers
diff --git a/doc/sphinx/tutorial/introduction.rst b/doc/sphinx/tutorial/introduction.rst
index c0a3a92..1f41b0f 100644
--- a/doc/sphinx/tutorial/introduction.rst
+++ b/doc/sphinx/tutorial/introduction.rst
@@ -4,15 +4,38 @@ What is Varnish?
----------------
Varnish Cache is a web application accelerator. It can also be called
-a HTTP reverse proxy. The next chapter :ref:`tutorial-web-accelerator`
-will go into detail on what Varnish is.
+a HTTP reverse proxy. It sits in front of a web server, accepts HTTP
+requests and tries to answer those by looking them up in it's
+cache. If it can't answer the request from cache it will hand the
+request over to a backend server.
+
+You can say that Varnish Cache is a specialized key-value store that
+stores HTTP responses. These are looked up with HTTP requests. If a
+match is found the content is delivered.
+
+Varnish Cache will typically look up a response by inspecting the HTTP
+Host header together with the URL. Varnish Cache maintains an index,
+a hash, with all the host+url combinations that are kept in the cache.
+
+Some times Varnish will refuse to store the content in it's
+cache. This might be because the HTTP reponse has metadata that
+disables cacheing or that there might be a cookie involved. Varnish,
+in the default configuration, will refuse to cache content when there
+are cookies involved because it has no idea if the content is derived
+from the cookie or not.
+
+All this behaviour can be changed using VCL. See the Users Guide for
+more information on how to do that.
+
Performance
~~~~~~~~~~~
Varnish has a modern architecture and is written with performance in
mind. It is usually bound by the speed of the network, effectivly
-turning performance into a non-issue.
+turning performance into a non-issue. You get to focus on how your web
+application work and you can allow yourself, to some degree, to care
+less about performance and scalability.
Flexibility
~~~~~~~~~~~
@@ -51,3 +74,5 @@ The are two mailing lists available. One for user questions and one
for development discussions. See varnish-cache.org/mailinglist for
information and signup. There is also a web forum on the same site.
+Now that you have a vague idea on what Varnish Cache is, let see if we
+can get it up and running.
diff --git a/doc/sphinx/tutorial/peculiarities.rst b/doc/sphinx/tutorial/peculiarities.rst
new file mode 100644
index 0000000..9e83e99
--- /dev/null
+++ b/doc/sphinx/tutorial/peculiarities.rst
@@ -0,0 +1,35 @@
+
+Peculiarities
+-------------
+
+There are a couple of things that are different with Varnish Cache, as
+opposed to other programs. One thing you've already seen - VCL. I'll
+just give you a very quick tour of the other pecularities.
+
+
+varnishadm
+~~~~~~~~~~
+
+Varnish Cache has an admin console. You can connect it it through the
+"varnishadm" command. In order to connect the user needs to be able to
+read /etc/varnish/secret in order to authenticate.
+
+Once you've started the console you can do quite a few operations on
+Varnish, like stopping and starting the cache process, load VCL,
+adjust the built in load balancer and invalidate cached content.
+
+It has a built in command "help" which will give you some hints on
+what it does.
+
+varnishlog
+~~~~~~~~~~
+
+Varnish does not log to disk. Instead it logs to a bit of memory. It
+is like a stream of logs. At any time you'll be able to connect to the
+stream and see what is going on. Varnish logs quite a bit of
+information. You can have a look at the logstream with the command
+``varnishlog``.
+
+
+
+
diff --git a/doc/sphinx/tutorial/putting_varnish_on_port_80.rst b/doc/sphinx/tutorial/putting_varnish_on_port_80.rst
index 73a80ff..05b8d17 100644
--- a/doc/sphinx/tutorial/putting_varnish_on_port_80.rst
+++ b/doc/sphinx/tutorial/putting_varnish_on_port_80.rst
@@ -3,23 +3,46 @@ Put Varnish on port 80
----------------------
Until now we've been running with Varnish on a high port, for testing
-purposes. You should test your application and if it works OK we can
-switch, so Varnish will be running on port 80 and your web server on a
-high port.
+purposes. You probably don't want to do this in the long term so let's
+put Varnish on port 80.
-First we kill off varnishd::
+First we stop varnish::
- # pkill varnishd
+ # service varnish stop
-and stop your web server. Edit the configuration for your web server
-and make it bind to port 8080 instead of 80. Now open the Varnish
-default.vcl and change the port of the *default* backend to 8080.
+Now we need to edit the configuration file that starts Varnish.
-Start up your web server and then start varnish::
- # varnishd -f /usr/local/etc/varnish/default.vcl -s malloc,1G -T 127.0.0.1:2000
+Debian/Ubuntu
+~~~~~~~~~~~~~
-Note that we've removed the -a option. Now Varnish, as its default
-setting dictates, will bind to the http port (80). Now everyone
-accessing your site will be accessing through Varnish.
+On Debian/Ubuntu this is /etc/default/varnish. In the file you'll find some text that looks like this::
+
+ DAEMON_OPTS="-a :6081 \
+ -T localhost:6082 \
+ -f /etc/varnish/default.vcl \
+ -S /etc/varnish/secret \
+ -s malloc,256m"
+
+Change it to::
+
+ DAEMON_OPTS="-a :80 \
+ -T localhost:6082 \
+ -f /etc/varnish/default.vcl \
+ -S /etc/varnish/secret \
+ -s malloc,256m"
+
+Red Hat EL / Centos
+~~~~~~~~~~~~~~~~~~~
+
+On Red Hat EL / Centos
+On Red Hat/Centos it is
+
+
+Restarting Varnish
+------------------
+
+Once the change is done. Restart varnish: ``service varnish
+restart``. Now everyone accessing your site will be accessing through
+Varnish.
diff --git a/doc/sphinx/tutorial/starting_varnish.rst b/doc/sphinx/tutorial/starting_varnish.rst
index fcdc37c..ed2ca12 100644
--- a/doc/sphinx/tutorial/starting_varnish.rst
+++ b/doc/sphinx/tutorial/starting_varnish.rst
@@ -1,35 +1,60 @@
.. _tutorial-starting_varnish:
+
Starting Varnish
----------------
-You might want to run ``pkill varnishd`` to make sure varnishd isn't
-already running. Become root and type:
-
-``# /usr/local/sbin/varnishd -f /usr/local/etc/varnish/default.vcl -s malloc,1G -a :80``
-
-I added a few options, lets go through them:
+This tutorial will assume that you are either running Ubuntu, Debian,
+Red Hat Enterprise Linux or Centos. Those of you running on other
+platforms might have to do some mental translation exercises in order
+to follow me. Since you're on a "weird" platform you're probably used
+to it. :-)
-``-f /usr/local/etc/varnish/default.vcl``
- The -f options specifies what configuration varnishd should use. If
- you are on a Linux system and have installed Varnish through packages
- the configuration files might reside in ``/etc/varnish``.
+I assume you have Varnish Cache installed.
-``-s malloc,1G``
- The -s options chooses the storage type Varnish should use for
- storing its content. I used the type *malloc*, which uses memory for
- storage. There are other backends as well, described in
- :ref:`user-guide-storage`. 1G specifies how much memory should be
- allocated - one gigabyte.
+You start Varnish with ``service varnish start``. This will start
+Varnish if it isn't already running.
Now you have Varnish running. Let us make sure that it works
-properly. Use your browser to go to http://192.168.2.2/
+properly. Use your browser to go to http://127.0.0.1:6081/
(obviously, you should replace the IP address with one on your own
-system) - you should now see your web application running there.
-
-There are many command line options available for Varnish. For a walk
-through the most important ones see :ref:`users-guide-command-line` or
-for a complete list see :ref:`ref-varnishd`.
-
-Ignore that for the moment, we'll revisit that topic in the Users
-Guide :ref:`users-guide-increasing_your_hitrate`.
+system).
+
+The default configuration will try to forward requests to a web
+service running on the same computer as Varnish was installed at,
+port 8080.
+
+If there is no web application being served up there Varnish will
+issue an error. Varnish Cache is very conservative about telling the
+world what is wrong so whenever something is amiss it will issue the
+same generic "Error 503 Service Unavilable".
+
+You might have a web application running on some other port or some
+other computer. Let's edit the configuration and make it point to
+something that actually works.
+
+Fire up your favorite editor and edit /etc/varnish/default.vcl. Most
+of it is commented out but there is some text that is not. It will
+probably look like this::
+
+ backend default {
+ .host = "127.0.0.1";
+ .port = "8080";
+ }
+
+We'll change it and make it point to something that works. Hopefully
+www.varnish-cache.org is up. Let's use that. Replace the text with::
+
+ backend default {
+ .host = "www.varnish-cache.org";
+ .port = "80";
+ }
+
+
+Now issue ``service varnish reload`` to make Varnish reload it's
+configuration. If that succeeded visit http://127.0.0.1:6081/ in your
+browser and you should see some directory listing. It works! The
+reason you're not seeing the Varnish official website is because your
+client isn't sending the appropriate Host: header in the request and
+it ends up showing a listing of the default webfolder on the machine
+usually serving up varnish-cache.org.
diff --git a/doc/sphinx/tutorial/web_accelerator.rst b/doc/sphinx/tutorial/web_accelerator.rst
deleted file mode 100644
index 28f8365..0000000
--- a/doc/sphinx/tutorial/web_accelerator.rst
+++ /dev/null
@@ -1,23 +0,0 @@
-.. _tutorial-web_accelerator:
-
-What is a web accelerator
--------------------------
-
-Really.XXX.
-
-
-The problem
------------
-
-Application servers er slow. They do lots of different things and
-they can sometimes take seconds to complete a web page.
-
-The solution
-------------
-
-Enter Varnish. It keeps a copy of the web pages that pass through
-it. If it finds that it can reuse these later so the server doesn't
-have to regenerate these it speeds things up.
-
-
-
More information about the varnish-commit
mailing list