[master] 6e7b2b2 Align documentation with new defaults.

[Poul-Henning Kamp]

commit 6e7b2b22b1ea01a0db173cbbcd1c28672b2823a4
Author: Poul-Henning Kamp <phk at FreeBSD.org>
Date:   Mon Nov 11 08:44:21 2013 +0000

    Align documentation with new defaults.

diff --git a/doc/sphinx/users-guide/command-line.rst b/doc/sphinx/users-guide/command-line.rst
index d3b5240..ea44323 100644
--- a/doc/sphinx/users-guide/command-line.rst
+++ b/doc/sphinx/users-guide/command-line.rst
@@ -1,27 +1,30 @@
 .. _users-guide-command-line:
 
-Typical command line options
-----------------------------
+Important command line arguments
+--------------------------------
 
-If you run Varnish out of a package for your operating system,
-you will find the default options here:
+There a two command line arguments you will simply have choose
+values for, what TCP port serve HTTP from and where the backend
+server can be contacted.
+
+If you run Varnish from a package for your operating system,
+you will find the startup options here:
 
 * Debian, Ubuntu: /etc/default/varnish
 * Red Hat, Centos: /etc/sysconfig/varnish
 * FreeBSD: /etc/rc.conf (See also: /usr/local/etc/rc.d/varnishd)
 
-There some command line options you will simply have choose values for:
 
 -a *listen_address*
 ^^^^^^^^^^^^^^^^^^^
 
-What address should Varnish listen to and service HTTP requests on.
+What address should Varnish listen to, and service HTTP requests from.
 
 You will most likely want to set this to ":80" which is the Well
 Known Port for HTTP.
 
 You can specify multiple addresses separated by a comma, and you
-can use numeric or host/service names as you like, varnish will try
+can use numeric or host/service names if you like, varnish will try
 to open and service as many of them as possible, but if none of them
 can be opened, varnishd will not start.
 
@@ -40,8 +43,7 @@ it to another port number first.
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Varnish needs to know where to find the HTTP server it is caching for.
-You can either specify it with -b and use the default VCL code, or you
-can put it in your own VCL file.
+You can either specify it with -b, or you can put it in your own VCL file.
 
 Using -b is a quick way to get started::
 
@@ -60,38 +62,26 @@ If you go with -f, you can start with a VCL file containing just::
 
 which is exactly what -b does.
 
--s *storage-options*
-^^^^^^^^^^^^^^^^^^^^
-
-This is probably the most important one. The default is to use
-the memory storage backend and to allocate a small amount of
-memory. On a small site this might suffice. If you have dedicated
-Varnish Cache server you most definitivly want to increase
-the memory allocated or consider another backend. 
-Please note that in addition to the memory allocated by the
-storage engine itself Varnish also has internal data structures
-that consume memory. More or less 1kb per object.  
-See also :ref:`guide-storage`.
-
--T *CLI-listen-address*  
-^^^^^^^^^^^^^^^^^^^^^^^
-
-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.
-
--S *CLI-secret-file*
-^^^^^^^^^^^^^^^^^^^^
-
-This file stores a secret you must know, in order to get
-access to the CLI.
+In both cases the default VCL code is appended.
+
+Other options
+^^^^^^^^^^^^^
+
+Varnish has more command line arguments you can and maybe want
+to tweak, but to get started, the above will be sufficient.
+
+By default Varnish will use 100 megabytes of malloc(3) storage
+for caching objects, if you want to cache more than that, you
+should look at the '-s' argument.
+
+If you run a really big site, you may want to tune the size of
+the tread-pools and other parameters with the '-p' argument,
+but we generally advice not to do that, unless you need to.
+
+Before you go into production, you may also want to re-visit the
+chapter
+:ref:`run_security` to see if you need to partition administrative
+privileges.
 
 For a complete list of the command line parameters please see
 :ref:`ref-varnishd-options`.
-
diff --git a/doc/sphinx/users-guide/run_security.rst b/doc/sphinx/users-guide/run_security.rst
index 29862b3..7eda18e 100644
--- a/doc/sphinx/users-guide/run_security.rst
+++ b/doc/sphinx/users-guide/run_security.rst
@@ -53,7 +53,11 @@ much anything the kernel will accept::
 	-T 192.168.1.1:34
 	-T '[fe80::1]:8082'
 
-By using a "localhost" address, you can restrict CLI access
+The default is '-T localhost:0' which will pick a random
+port number, which varnishadm(8) can learn in the shared
+memory.
+
+By using a "localhost" address, you restrict CLI access
 to the local machine.
 
 You can also bind the CLI port to an IP number reachable across