[master] f125f37 Making the user guide more user guidery
Per Buer
perbu at varnish-cache.org
Fri Sep 7 15:23:19 CEST 2012
commit f125f37903c4507973248406fd778de1ace870f9
Author: Per Buer <per.buer at gmail.com>
Date: Fri Sep 7 15:23:13 2012 +0200
Making the user guide more user guidery
diff --git a/doc/sphinx/users-guide/advanced_topics.rst b/doc/sphinx/users-guide/advanced_topics.rst
index 07e5237..6368d6e 100644
--- a/doc/sphinx/users-guide/advanced_topics.rst
+++ b/doc/sphinx/users-guide/advanced_topics.rst
@@ -19,6 +19,8 @@ page - ref:`reference-vcl`.
Using In-line C to extend Varnish
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+(Here there be dragons)
+
You can use *in-line C* to extend Varnish. Please note that you can
seriously mess up Varnish this way. The C code runs within the Varnish
Cache process so if your code generates a segfault the cache will crash.
@@ -37,27 +39,3 @@ One of the first uses I saw of In-line C was logging to syslog.::
}
-Edge Side Includes
-~~~~~~~~~~~~~~~~~~
-
-Varnish can cache create web pages by putting different pages
-together. These *fragments* can have individual cache policies. If you
-have a web site with a list showing the 5 most popular articles on
-your site, this list can probably be cached as a fragment and included
-in all the other pages. Used properly it can dramatically increase
-your hit rate and reduce the load on your servers. ESI looks like this::
-
- <HTML>
- <BODY>
- The time is: <esi:include src="/cgi-bin/date.cgi"/>
- at this very moment.
- </BODY>
- </HTML>
-
-ESI is processed in vcl_fetch by setting *do_esi* to true.::
-
- sub vcl_fetch {
- if (req.url == "/test.html") {
- set beresp.do_esi = true; /* Do ESI processing */
- }
- }
diff --git a/doc/sphinx/users-guide/command_line.rst b/doc/sphinx/users-guide/command_line.rst
index 94d8f5c..318868f 100644
--- a/doc/sphinx/users-guide/command_line.rst
+++ b/doc/sphinx/users-guide/command_line.rst
@@ -1,5 +1,7 @@
.. _users-guide-command-line:
+XXX: Total rewrite of this
+
Starting Varnish
----------------
diff --git a/doc/sphinx/users-guide/esi.rst b/doc/sphinx/users-guide/esi.rst
index afd6e14..8a12461 100644
--- a/doc/sphinx/users-guide/esi.rst
+++ b/doc/sphinx/users-guide/esi.rst
@@ -3,14 +3,12 @@
Edge Side Includes
------------------
-*Edge Side Includes* is a language to include *fragments* of web pages
-in other web pages. Think of it as HTML include statement that works
-over HTTP.
-
-On most web sites a lot of content is shared between
-pages. Regenerating this content for every page view is wasteful and
-ESI tries to address that letting you decide the cache policy for
-each fragment individually.
+Varnish can cache create web pages by putting different pages
+together. These *fragments* can have individual cache policies. If you
+have a web site with a list showing the 5 most popular articles on
+your site, this list can probably be cached as a fragment and included
+in all the other pages. Used properly it can dramatically increase
+your hit rate and reduce the load on your servers.
In Varnish we've only implemented a small subset of ESI. As of 2.1 we
have three ESI statements:
@@ -20,7 +18,8 @@ have three ESI statements:
* <!--esi ...-->
Content substitution based on variables and cookies is not implemented
-but is on the roadmap.
+but is on the roadmap. At least if you look at the roadmap from a
+certain angle. During a full moon.
Varnish will not process ESI instructions in HTML comments.
@@ -77,3 +76,11 @@ For example::
<p>The full text of the license:</p>
<esi:include src="http://example.com/LICENSE" />
-->
+
+Doing ESI on JSON and other non-XMLish content
+----------------------------------------------
+
+Please note that Varnish will peek at the included content. If it
+doesn't start with a "<" Varnish assumes you didn't really mean to
+include it and disregard it. You can alter this behaviour by setting
+the esi_syntax parameter (see ref:`ref-varnishd`).
\ No newline at end of file
diff --git a/doc/sphinx/users-guide/index.rst b/doc/sphinx/users-guide/index.rst
index 024738b..dacb13d 100644
--- a/doc/sphinx/users-guide/index.rst
+++ b/doc/sphinx/users-guide/index.rst
@@ -5,13 +5,10 @@ Using Varnish
%%%%%%%%%%%%%
This guide is intended for system administrators managing Varnish
-Cache. The reader should know how to configure her web- or application
-server and have basic knowledge of the HTTP protocol. The reader
-should have Varnish Cache up and running with the default
-configuration.
+Cache.
-The guide is split into short chapters, each chapter taking on a
-separate topic. Good luck.
+The guide is split into short chapters, each chapter explaining a
+separate topic.
.. toctree:: :maxdepth: 1
@@ -24,13 +21,13 @@ separate topic. Good luck.
increasing_your_hitrate
cookies
vary
+ hashing
purging
compression
esi
virtualized
websockets
devicedetection
- advanced_backend_servers
handling_misbehaving_servers
advanced_topics
troubleshooting
diff --git a/doc/sphinx/users-guide/logging.rst b/doc/sphinx/users-guide/logging.rst
index f2e36fd..01d8f36 100644
--- a/doc/sphinx/users-guide/logging.rst
+++ b/doc/sphinx/users-guide/logging.rst
@@ -7,7 +7,8 @@ One of the really nice features in Varnish is how logging
works. Instead of logging to normal log file Varnish logs to a shared
memory segment. When the end of the segment is reached we start over,
overwriting old data. This is much, much faster then logging to a file
-and it doesn't require disk space.
+and it doesn't require disk space. Besides it gives you much, much
+more information when you need it.
The flip side is that if you forget to have a program actually write the
logs to disk they will disappear.
@@ -64,5 +65,4 @@ want to know are:
Only list transactions where the tag matches a regular expression. If
it matches you will get the whole transaction.
-Now that Varnish seem to work OK it's time to put Varnish on port 80
-while we tune it.
+For more information on this topic please see ref:`ref-varnishlog`.
diff --git a/doc/sphinx/users-guide/sizing_your_cache.rst b/doc/sphinx/users-guide/sizing_your_cache.rst
index c19647c..7d48200 100644
--- a/doc/sphinx/users-guide/sizing_your_cache.rst
+++ b/doc/sphinx/users-guide/sizing_your_cache.rst
@@ -12,10 +12,10 @@ task. A few things to consider:
to only cache images a little while or not to cache them at all if
they are cheap to serve from the backend and you have a limited
amount of memory.
- * Watch the n_lru_nuked counter with :ref:`reference-varnishstat` or some other
- tool. If you have a lot of LRU activity then your cache is evicting
- objects due to space constraints and you should consider increasing
- the size of the cache.
+ * Watch the n_lru_nuked counter with :ref:`reference-varnishstat` or
+ some other tool. If you have a lot of LRU activity then your cache
+ is evicting objects due to space constraints and you should
+ consider increasing the size of the cache.
Be aware that every object that is stored also carries overhead that
is kept outside the actually storage area. So, even if you specify -s
diff --git a/doc/sphinx/users-guide/troubleshooting.rst b/doc/sphinx/users-guide/troubleshooting.rst
index e1df5f2..be24e7a 100644
--- a/doc/sphinx/users-guide/troubleshooting.rst
+++ b/doc/sphinx/users-guide/troubleshooting.rst
@@ -63,14 +63,11 @@ errors will be logged in syslog. It might look like this::
Mar 8 13:23:43 smoke varnishd[15670]: Child cleanup complete
Mar 8 13:23:43 smoke varnishd[15670]: child (15697) Started
-Specifically if you see the "Error in munmap" error on Linux you might
-want to increase the amount of maps available. Linux is limited to a
-maximum of 64k maps. Setting vm.max_max_count i sysctl.conf will
-enable you to increase this limit. You can inspect the number of maps
-your program is consuming by counting the lines in /proc/$PID/maps
-
-This is a rather odd thing to document here - but hopefully Google
-will serve you this page if you ever encounter this error.
+In this situation the mother process assumes that the cache died and
+killed it off.
+
+XXX: Describe crashing child process and crashing mother process here too.
+XXX: panic.show
Varnish gives me Guru meditation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/sphinx/users-guide/virtualized.rst b/doc/sphinx/users-guide/virtualized.rst
index 317d3e2..5fc59b6 100644
--- a/doc/sphinx/users-guide/virtualized.rst
+++ b/doc/sphinx/users-guide/virtualized.rst
@@ -1,4 +1,6 @@
+XXX: What is this doing here?
+
Running Varnish in a virtualized environment
--------------------------------------------
More information about the varnish-commit
mailing list