[master] 060e644 More tutorial --> users guide stuff
Per Buer
perbu at varnish-cache.org
Thu Sep 6 13:56:48 CEST 2012
commit 060e64492bded482613f64876bab0bc5bff08ec8
Author: Per Buer <perbu at varnish-software.com>
Date: Thu Sep 6 13:56:43 2012 +0200
More tutorial --> users guide stuff
diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst
index 06eb52a..9f367c3 100644
--- a/doc/sphinx/index.rst
+++ b/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
diff --git a/doc/sphinx/users-guide/advanced_backend_servers.rst b/doc/sphinx/users-guide/advanced_backend_servers.rst
index b4206d9..52af46e 100644
--- a/doc/sphinx/users-guide/advanced_backend_servers.rst
+++ b/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
diff --git a/doc/sphinx/users-guide/advanced_topics.rst b/doc/sphinx/users-guide/advanced_topics.rst
index 1045de9..07e5237 100644
--- a/doc/sphinx/users-guide/advanced_topics.rst
+++ b/doc/sphinx/users-guide/advanced_topics.rst
@@ -1,12 +1,12 @@
-.. _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
~~~~~~~~
diff --git a/doc/sphinx/users-guide/backend_servers.rst b/doc/sphinx/users-guide/backend_servers.rst
index 1b1aaf2..695a21a 100644
--- a/doc/sphinx/users-guide/backend_servers.rst
+++ b/doc/sphinx/users-guide/backend_servers.rst
@@ -1,4 +1,4 @@
-.. _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.
diff --git a/doc/sphinx/users-guide/command_line.rst b/doc/sphinx/users-guide/command_line.rst
new file mode 100644
index 0000000..94d8f5c
--- /dev/null
+++ b/doc/sphinx/users-guide/command_line.rst
@@ -0,0 +1,53 @@
+.. _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.
diff --git a/doc/sphinx/users-guide/compression.rst b/doc/sphinx/users-guide/compression.rst
index 0b8d1e8..1e93384 100644
--- a/doc/sphinx/users-guide/compression.rst
+++ b/doc/sphinx/users-guide/compression.rst
@@ -1,4 +1,4 @@
-.. _tutorial-compression:
+.. _users-guide-compression:
Compression
~~~~~~~~~~~
diff --git a/doc/sphinx/users-guide/cookies.rst b/doc/sphinx/users-guide/cookies.rst
index c75171f..1df1851 100644
--- a/doc/sphinx/users-guide/cookies.rst
+++ b/doc/sphinx/users-guide/cookies.rst
@@ -1,4 +1,4 @@
-.. _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.
diff --git a/doc/sphinx/users-guide/devicedetection.rst b/doc/sphinx/users-guide/devicedetection.rst
index 6bfc4c9..13d501a 100644
--- a/doc/sphinx/users-guide/devicedetection.rst
+++ b/doc/sphinx/users-guide/devicedetection.rst
@@ -1,4 +1,4 @@
-.. _tutorial-devicedetect:
+.. _users-guide-devicedetect:
Device detection
~~~~~~~~~~~~~~~~
diff --git a/doc/sphinx/users-guide/esi.rst b/doc/sphinx/users-guide/esi.rst
index 720b790..afd6e14 100644
--- a/doc/sphinx/users-guide/esi.rst
+++ b/doc/sphinx/users-guide/esi.rst
@@ -1,4 +1,4 @@
-.. _tutorial-esi:
+.. _users-guide-esi:
Edge Side Includes
------------------
diff --git a/doc/sphinx/users-guide/handling_misbehaving_servers.rst b/doc/sphinx/users-guide/handling_misbehaving_servers.rst
index 406b4b3..bb5fd35 100644
--- a/doc/sphinx/users-guide/handling_misbehaving_servers.rst
+++ b/doc/sphinx/users-guide/handling_misbehaving_servers.rst
@@ -1,4 +1,4 @@
-.. _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.::
diff --git a/doc/sphinx/users-guide/increasing_your_hitrate.rst b/doc/sphinx/users-guide/increasing_your_hitrate.rst
index b9fa7e6..462a781 100644
--- a/doc/sphinx/users-guide/increasing_your_hitrate.rst
+++ b/doc/sphinx/users-guide/increasing_your_hitrate.rst
@@ -1,4 +1,4 @@
-.. _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`
diff --git a/doc/sphinx/users-guide/index.rst b/doc/sphinx/users-guide/index.rst
index 6cf20a2..024738b 100644
--- a/doc/sphinx/users-guide/index.rst
+++ b/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
diff --git a/doc/sphinx/users-guide/logging.rst b/doc/sphinx/users-guide/logging.rst
index 1f0bc18..f2e36fd 100644
--- a/doc/sphinx/users-guide/logging.rst
+++ b/doc/sphinx/users-guide/logging.rst
@@ -1,4 +1,4 @@
-.. _tutorial-logging:
+.. _users-guide-logging:
Logging in Varnish
------------------
diff --git a/doc/sphinx/users-guide/purging.rst b/doc/sphinx/users-guide/purging.rst
index 422f9f4..15b85d2 100644
--- a/doc/sphinx/users-guide/purging.rst
+++ b/doc/sphinx/users-guide/purging.rst
@@ -1,4 +1,4 @@
-.. _tutorial-purging:
+.. _users-guide-purging:
=====================
Purging and banning
diff --git a/doc/sphinx/users-guide/statistics.rst b/doc/sphinx/users-guide/statistics.rst
index 4386111..ad57037 100644
--- a/doc/sphinx/users-guide/statistics.rst
+++ b/doc/sphinx/users-guide/statistics.rst
@@ -1,4 +1,4 @@
-.. _tutorial-statistics:
+.. _users-guide-statistics:
Statistics
diff --git a/doc/sphinx/users-guide/troubleshooting.rst b/doc/sphinx/users-guide/troubleshooting.rst
index 5bbcf6c..e1df5f2 100644
--- a/doc/sphinx/users-guide/troubleshooting.rst
+++ b/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`.
diff --git a/doc/sphinx/users-guide/vary.rst b/doc/sphinx/users-guide/vary.rst
index ad7b48d..8b6fa2b 100644
--- a/doc/sphinx/users-guide/vary.rst
+++ b/doc/sphinx/users-guide/vary.rst
@@ -1,4 +1,4 @@
-.. _tutorial-vary:
+.. _users-guide-vary:
Vary
~~~~
diff --git a/doc/sphinx/users-guide/vcl.rst b/doc/sphinx/users-guide/vcl.rst
index 0601468..57fb7e0 100644
--- a/doc/sphinx/users-guide/vcl.rst
+++ b/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
~~~~~~~
More information about the varnish-commit
mailing list