More tutorial --> users guide stuff

doc/sphinx/index.rst

@@ -20,6 +20,7 @@ Contents:
 
    installation/index.rst
    tutorial/index.rst
+   users-guide/index.rst
    reference/index.rst
    phk/index.rst
    glossary/index.rst

doc/sphinx/users-guide/advanced_backend_servers.rst

@@ -40,7 +40,7 @@ really arbitrary data. You want to send mobile devices to a different
 backend? No problem. if (req.User-agent ~ /mobile/) .... should do the
 trick. 
 
-.. _tutorial-advanced_backend_servers-directors:
+.. _users-guide-advanced_backend_servers-directors:
 
 Directors
 ---------
@@ -80,7 +80,7 @@ But what if one of your servers goes down? Can Varnish direct all the
 requests to the healthy server? Sure it can. This is where the Health
 Checks come into play.
 
-.. _tutorial-advanced_backend_servers-health:
+.. _users-guide-advanced_backend_servers-health:
 
 Health checks
 -------------
@@ -148,7 +148,7 @@ Now we define the director.::
 You use this director just as you would use any other director or
 backend. Varnish will not send traffic to hosts that are marked as
 unhealthy. Varnish can also serve stale content if all the backends are
-down. See :ref:`tutorial-handling_misbehaving_servers` for more
+down. See :ref:`users-guide-handling_misbehaving_servers` for more
 information on how to enable this.
 
 Please note that Varnish will keep probes active for all loaded

doc/sphinx/users-guide/advanced_topics.rst

-.. _tutorial-advanced_topics:
+.. _users-guide-advanced_topics:
 
 Advanced topics
 ---------------
 
-This tutorial has covered the basics in Varnish. If you read through
+This guide has covered the basics in Varnish. If you read through
 it all you should now have the skills to run Varnish.
 
-Here is a short overview of topics that we haven't covered in the tutorial. 
+Here is a short overview of topics that we haven't covered in the guide. 
 
 More VCL
 ~~~~~~~~

doc/sphinx/users-guide/backend_servers.rst

-.. _tutorial-backend_servers:
+.. _users-guide-backend_servers:
 
 Backend servers
 ---------------
@@ -19,8 +19,7 @@ Somewhere in the top there will be a section that looks a bit like this.::
 	  #     .port = "8080";
 	  # }
 
-We comment in this bit of text and change the port setting from 8080
-to 80, making the text look like.::
+We comment in this bit of text making the text look like.::
 
           backend default {
                 .host = "127.0.0.1";
@@ -29,11 +28,9 @@ to 80, making the text look like.::
 
 Now, this piece of configuration defines a backend in Varnish called
 *default*. When Varnish needs to get content from this backend it will
-connect to port 80 on localhost (127.0.0.1).
+connect to port 8080 on localhost (127.0.0.1).
 
 Varnish can have several backends defined and can you can even join
 several backends together into clusters of backends for load balancing
-purposes. 
+purposes.  XXX: ref
 
-Now that we have the basic Varnish configuration done, let us start up
-Varnish on port 8080 so we can do some fundamental testing on it.

doc/sphinx/users-guide/command_line.rst

+.. _users-guide-command-line:
+
+Starting Varnish
+----------------
+
+I assume varnishd is in your path. You might want to run ``pkill
+varnishd`` to make sure varnishd isn't running. 
+
+Become root and type:
+
+``# varnishd -f /usr/local/etc/varnish/default.vcl -s malloc,1G -T 127.0.0.1:2000 -a 0.0.0.0:8080``
+
+I added a few options, lets go through them:
+
+``-f /usr/local/etc/varnish/default.vcl``
+ The -f options specifies what configuration varnishd should use.
+
+``-s malloc,1G``
+ The -s options chooses the storage type Varnish should use for
+ storing its content. I used the type *malloc*, which just uses memory
+ for storage. There are other backends as well, described in 
+ :ref:users-guide-storage. 1G specifies how much memory should be allocated 
+ - one gigabyte. 
+
+``-T 127.0.0.1:2000``
+ Varnish has a built-in text-based administration
+ interface. Activating the interface makes Varnish manageble without
+ stopping it. You can specify what interface the management interface
+ should listen to. Make sure you don't expose the management interface
+ to the world as you can easily gain root access to a system via the
+ Varnish management interface. I recommend tieing it to localhost. If
+ you have users on your system that you don't fully trust, use firewall
+ rules to restrict access to the interface to root only.
+
+``-a 0.0.0.0:8080``
+ I specify that I want Varnish to listen on port 8080 for incomming
+ HTTP requests. For a production environment you would probably make
+ Varnish listen on port 80, which is the default.
+
+Now you have Varnish running. Let us make sure that it works
+properly. Use your browser to go to http://192.168.2.2:8080/
+(obviously, you should replace the IP address with one on your own
+system) - you should now see your web application running there.
+
+Whether or not the application actually goes faster when run through
+Varnish depends on a few factors. If you application uses cookies for
+every session (a lot of PHP and Java applications seem to send a
+session cookie if it is needed or not) or if it uses authentication
+chances are Varnish won't do much caching. Ignore that for the moment,
+we come back to that in :ref:`users-guide-increasing_your_hitrate`.
+
+Lets make sure that Varnish really does do something to your web
+site. To do that we'll take a look at the logs.

doc/sphinx/users-guide/compression.rst

-.. _tutorial-compression:
+.. _users-guide-compression:
 
 Compression
 ~~~~~~~~~~~

doc/sphinx/users-guide/cookies.rst

-.. _tutorial-cookies:
+.. _users-guide-cookies:
 
 Cookies
 -------
@@ -90,6 +90,6 @@ Cookies coming from the backend
 
 If your backend server sets a cookie using the Set-Cookie header
 Varnish will not cache the page in the default configuration.  A
-hit-for-pass object (see :ref:`tutorial-vcl_fetch_actions`) is created.
+hit-for-pass object (see :ref:`users-guide-vcl_fetch_actions`) is created.
 So, if the backend server acts silly and sets unwanted cookies just unset
 the Set-Cookie header and all should be fine. 

doc/sphinx/users-guide/devicedetection.rst

-.. _tutorial-devicedetect:
+.. _users-guide-devicedetect:
 
 Device detection
 ~~~~~~~~~~~~~~~~

doc/sphinx/users-guide/esi.rst

-.. _tutorial-esi:
+.. _users-guide-esi:
 
 Edge Side Includes
 ------------------

doc/sphinx/users-guide/handling_misbehaving_servers.rst

-.. _tutorial-handling_misbehaving_servers:
+.. _users-guide-handling_misbehaving_servers:
 
 Misbehaving servers
 -------------------
@@ -42,7 +42,7 @@ request. Lets us say that we accept serving 15s old object.::
 
 You might wonder why we should keep the objects in the cache for 30
 minutes if we are unable to serve them? Well, if you have enabled
-:ref:`tutorial-advanced_backend_servers-health` you can check if the
+:ref:`users-guide-advanced_backend_servers-health` you can check if the
 backend is sick and if it is we can serve the stale content for a bit
 longer.::
 

doc/sphinx/users-guide/increasing_your_hitrate.rst

-.. _tutorial-increasing_your_hitrate:
+.. _users-guide-increasing_your_hitrate:
 
 Achieving a high hitrate
 ------------------------
@@ -24,7 +24,7 @@ Tool: varnishtop
 
 You can use varnishtop to identify what URLs are hitting the backend
 the most. ``varnishtop -i txurl`` is an essential command. You can see
-some other examples of varnishtop usage in :ref:`tutorial-statistics`.
+some other examples of varnishtop usage in :ref:`users-guide-statistics`.
 
 
 Tool: varnishlog
@@ -36,7 +36,7 @@ backend you can use varnishlog to have a look at the request.
 coming from the client (-c) matching /foo/bar.
 
 For more information on how varnishlog works please see
-:ref:`tutorial-logging` or man :ref:`ref-varnishlog`.
+:ref:`users-guide-logging` or man :ref:`ref-varnishlog`.
 
 For extended diagnostics headers, see
 http://www.varnish-cache.org/trac/wiki/VCLExampleHitMissHeader
@@ -206,8 +206,8 @@ Ways of increasing your hitrate even more
 The following chapters should give your ways of further increasing
 your hitrate, especially the chapter on Cookies.
 
- * :ref:`tutorial-cookies`
- * :ref:`tutorial-vary`
- * :ref:`tutorial-purging`
- * :ref:`tutorial-esi`
+ * :ref:`users-guide-cookies`
+ * :ref:`users-guide-vary`
+ * :ref:`users-guide-purging`
+ * :ref:`users-guide-esi`
 

doc/sphinx/users-guide/index.rst

@@ -10,17 +10,15 @@ server and have basic knowledge of the HTTP protocol. The reader
 should have Varnish Cache up and running with the default
 configuration.
 
-The tutorial is split into short chapters, each chapter taking on a
+The guide is split into short chapters, each chapter taking on a
 separate topic. Good luck.
 
 .. toctree:: :maxdepth: 1
 
-        introduction
+        command_line
 	backend_servers
-        starting_varnish
 	logging
         sizing_your_cache
-        putting_varnish_on_port_80
 	vcl
         statistics
         increasing_your_hitrate

doc/sphinx/users-guide/logging.rst

-.. _tutorial-logging:
+.. _users-guide-logging:
 
 Logging in Varnish
 ------------------

doc/sphinx/users-guide/purging.rst

-.. _tutorial-purging:
+.. _users-guide-purging:
 
 =====================
  Purging and banning

doc/sphinx/users-guide/statistics.rst

-.. _tutorial-statistics:
+.. _users-guide-statistics:
 
 
 Statistics

doc/sphinx/users-guide/troubleshooting.rst

@@ -95,5 +95,5 @@ filtering capabilities and explanation of the various options.
 Varnish doesn't cache
 ~~~~~~~~~~~~~~~~~~~~~
 
-See :ref:`tutorial-increasing_your_hitrate`.
+See :ref:`users-guide-increasing_your_hitrate`.
 

doc/sphinx/users-guide/vary.rst

-.. _tutorial-vary:
+.. _users-guide-vary:
 
 Vary
 ~~~~

doc/sphinx/users-guide/vcl.rst

@@ -49,7 +49,7 @@ In vcl_fetch you still have the request object, req, available. There
 is also a *backend response*, beresp. beresp will contain the HTTP
 headers from the backend.
 
-.. _tutorial-vcl_fetch_actions:
+.. _users-guide-vcl_fetch_actions:
 
 actions
 ~~~~~~~