[4.0] 70b1004 Run-through of the first chapter in the docs
Lasse Karstensen
lkarsten at varnish-software.com
Thu Mar 13 10:24:30 CET 2014
commit 70b1004ce4adbc52f5c872972cba9738862c9114
Author: Lasse Karstensen <lkarsten at varnish-software.com>
Date: Tue Mar 4 14:43:37 2014 +0100
Run-through of the first chapter in the docs
I'm happy with the first chapter for 4.0 release.
diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst
index e83d1dc..dde63a6 100644
--- a/doc/sphinx/index.rst
+++ b/doc/sphinx/index.rst
@@ -15,12 +15,24 @@
Welcome to the Varnish documentation!
=====================================
+Introduction
+------------
+
Varnish is a state of the art web accelerator. It has its mission in front of a
-web server and cache content. It makes your web site go faster.
+web server and cache content.
+
+It makes your web site go faster.
We suggest you start by reading the installation guide
:ref:`install-index`. Once you have Varnish up and running go through
-our tutorial - :ref:`tutorial-index`.
+our tutorial - :ref:`tutorial-index`, and finally the :ref:`users_guide_index`.
+
+If you need to look up how a specific Varnish tool works, the
+:ref:`reference-index` can help you out. Changes from previous versions are in
+the :ref:`whats-new-index` chapter. In closing we have :ref:`phk`, a collection
+of blog posts related to Varnish and HTTP.
+
+
.. toctree::
:maxdepth: 1
diff --git a/doc/sphinx/installation/bugs.rst b/doc/sphinx/installation/bugs.rst
index 16f0c51..98c0e19 100644
--- a/doc/sphinx/installation/bugs.rst
+++ b/doc/sphinx/installation/bugs.rst
@@ -28,11 +28,11 @@ Varnish crashes
Plain and simple: **boom**
Varnish is split over two processes, the manager and the child. The child
-does all the work, and the manager hangs around to resurect it if it
+does all the work, and the manager hangs around to resurrect it if it
crashes.
Therefore, the first thing to do if you see a Varnish crash, is to examine
-your syslogs, to see if it has happened before. (One site is rumoured
+your syslogs to see if it has happened before. (One site is rumoured
to have had Varnish restarting every 10 minutes and *still* provide better
service than their CMS system.)
@@ -138,11 +138,11 @@ transactions recorded with ``varnishlog`` and your explanation of
what is wrong about what Varnish does.
Be aware, that often Varnish does exactly what you asked it to, rather
-than what you intended it to do, so it sounds like a bug that would
+than what you intended it to do. If it sounds like a bug that would
have tripped up everybody else, take a moment to read though your
VCL and see if it really does what you think.
-You can also try setting the ``vcl_trace`` parameter, that will
-generate log records with like and char number for each statement
-executed in your VCL program.
+You can also try setting the ``vcl_trace`` parameter, that will generate log
+records with like and character number for each statement executed in your VCL
+program.
diff --git a/doc/sphinx/installation/help.rst b/doc/sphinx/installation/help.rst
index 4fb8362..aaea9ec 100644
--- a/doc/sphinx/installation/help.rst
+++ b/doc/sphinx/installation/help.rst
@@ -7,7 +7,7 @@ we try to help as much as time permits and have tried to streamline
this process as much as possible.
But before you grab hold of us, spend a moment composing your thoughts and
-formulate your question, there is nothing as pointless as simply telling
+formulate your question. There is nothing as pointless as simply telling
us "Varnish does not work for me" with no further information to give
any clue to why.
@@ -18,15 +18,15 @@ much faster that way.
IRC Channel
===========
-The most immediate way to get hold of us, is to join our IRC channel:
+The most immediate way to get hold of us is to join our IRC channel:
``#varnish on server irc.linpro.no``
-The main timezone of the channel is Europe+America.
+The main timezone of the channel is Europe work hours.
If you can explain your problem in a few clear sentences, without too
much copy&paste, IRC is a good way to try to get help. If you do need
-to paste log files, VCL and so on, please use a pastebin_.
+to paste log files, VCL and so on, please use a pastebin_ service.
If the channel is all quiet, try again some time later, we do have lives,
families and jobs to deal with also.
@@ -39,7 +39,7 @@ it mostly on topic, and don't paste random links unless they are
Mailing Lists
=============
-Getting on or off our mailing lists happens through MailMan_.
+Getting on or off our mailing lists happens through Mailman_.
If you are going to use Varnish, subscribing to our ``varnish-announce``
mailing list is probably a very good idea. The typical pattern is that
@@ -66,6 +66,10 @@ usually quite focused on source-code and such. Everybody on
the -dev list is also on -misc, so cross-posting only serves to annoy
those people.
+.. XXX: we should introduce the wiki (if we care about it) before
+.. we start referring to it (below). Make a wiki chapter?
+
+
Trouble Tickets
===============
@@ -90,6 +94,6 @@ an email to phk at FreeBSD.org.
sales at varnish-software.com
-.. _Mailman: http://lists.varnish-cache.org/mailman/listinfo
+.. _mailman: http://lists.varnish-cache.org/mailman/listinfo
.. _pastebin: http://gist.github.com/
.. _"Shopping-List" wiki page: http://varnish-cache.org/wiki/PostTwoShoppingList
diff --git a/doc/sphinx/installation/index.rst b/doc/sphinx/installation/index.rst
index 60d43e0..0b0c665 100644
--- a/doc/sphinx/installation/index.rst
+++ b/doc/sphinx/installation/index.rst
@@ -5,10 +5,13 @@ Varnish Installation
%%%%%%%%%%%%%%%%%%%%
This document explains how to get Varnish onto your system, where
-to get help, how report bugs and so on. In other words, it is a manual
-about pretty much everything else than actually using Varnish to
+to get help, how report bugs and so on.
+
+In other words, it is a manual about pretty much everything else than actually using Varnish to
move traffic.
+.. XXX: rewrite the last paragraph.
+
.. toctree::
prerequisites.rst
diff --git a/doc/sphinx/installation/install.rst b/doc/sphinx/installation/install.rst
index 45c5e4e..a32eb68 100644
--- a/doc/sphinx/installation/install.rst
+++ b/doc/sphinx/installation/install.rst
@@ -4,7 +4,7 @@ Installing Varnish
==================
With open source software, you can choose to install binary packages
-or compile stuff from source-code. To install a package or compile
+or compile it yourself from source code. To install a package or compile
from source is a matter of personal taste. If you don't know which
method to choose, read the whole document and choose the method you
are most comfortable with.
@@ -29,7 +29,7 @@ CentOS/RedHat
-------------
We try to keep the latest version available as prebuilt RPMs (el5 and el6)
-on `repo.varnish-cache.org <http://repo.varnish-cache.org/>`_. See the
+on `repo.varnish-cache.org <http://repo.varnish-cache.org/>`_. See the online
`RedHat installation instructions
<http://www.varnish-cache.org/installation/redhat>`_ for more information.
@@ -46,7 +46,7 @@ Debian/Ubuntu
Varnish is distributed with both Debian and Ubuntu. In order to get
Varnish up and running type `sudo apt-get install varnish`. Please
note that this might not be the latest version of Varnish. If you
-need a later version of Varnish, please follow the installation
+need a later version of Varnish, please follow the online installation
instructions for `Debian
<http://www.varnish-cache.org/installation/debian>`_ or `Ubuntu
<http://www.varnish-cache.org/installation/ubuntu>`_.
@@ -92,10 +92,10 @@ If you're building from git, you also need the following:
* python-docutils
* python-sphinx (optional, if you want to build the documentation)
-Build dependencies on Red Hat / CentOS
+Build dependencies on RedHat / CentOS
--------------------------------------
-To build Varnish on a Red Hat or CentOS system you need the following
+To build Varnish on a RedHat or CentOS system you need the following
packages installed:
* automake
@@ -115,8 +115,8 @@ If you're building from git, you also need the following:
Compiling Varnish
-----------------
-Next, configuration: The configuration will need the dependencies
-above satisfied. Once that is taken care of::
+The configuration will need the dependencies above satisfied. Once that is
+taken care of::
cd varnish-cache
sh autogen.sh
@@ -124,7 +124,7 @@ above satisfied. Once that is taken care of::
make
The ``configure`` script takes some arguments, but more likely than
-not, you can forget about that for now, almost everything in Varnish
+not you can forget about that for now, almost everything in Varnish
are run time parameters.
Before you install, you may want to run the test suite, make a cup of
@@ -143,10 +143,11 @@ Installing
And finally, the true test of a brave heart::
- make install
+ sudo make install
Varnish will now be installed in /usr/local. The varnishd binary is in
/usr/local/sbin/varnishd and its default configuration will be
/usr/local/etc/varnish/default.vcl.
You can now proceed to the :ref:`tutorial-index`.
+
diff --git a/doc/sphinx/installation/platformnotes.rst b/doc/sphinx/installation/platformnotes.rst
index bacc57e..a7d3fb4 100644
--- a/doc/sphinx/installation/platformnotes.rst
+++ b/doc/sphinx/installation/platformnotes.rst
@@ -2,6 +2,10 @@
Platform specific notes
------------------------
+On some platforms it is necessary to adjust the operating system before running
+Varnish on it. The systems and steps known to us are described in this section.
+
+
Transparent hugepages on Redhat Enterprise Linux 6
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -12,7 +16,8 @@ It is recommended to disable transparent hugepages on affected systems::
$ echo "never" > /sys/kernel/mm/redhat_transparent_hugepage/enabled
-On Debian/Ubuntu systems running 3.2 kernels the default value is "madvise" and does not need to changed.
+On Debian/Ubuntu systems running 3.2 kernels the default value is "madvise" and
+does not need to be changed.
OpenVZ
@@ -38,12 +43,12 @@ in the Varnish startup script.
TCP keep-alive configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-On some systems, Varnish is not able to set the TCP keep-alive values
-per socket, and therefor the tcp_keepalive_* Varnish runtime
-parameters are not available. On these platforms it can be benefitial
-to tune the system wide values for these in order to more reliably
-detect remote close for sessions spending long time on
-waitinglists. This will help free up resources faster.
+On some Solaris, FreeBSD and OS X systems, Varnish is not able to set the TCP
+keep-alive values per socket, and therefor the tcp_keepalive_* Varnish runtime
+parameters are not available. On these platforms it can be benefitial to tune
+the system wide values for these in order to more reliably detect remote close
+for sessions spending long time on waitinglists. This will help free up
+resources faster.
Systems to not support TCP keep-alive values per socket include:
More information about the varnish-commit
mailing list