Trains are good for writing documentation :-)

doc/sphinx/users-guide/command-line.rst

@@ -3,46 +3,94 @@
 Typical command line options
 ----------------------------
 
-On a modern Linux distro the various options that are used when
-starting up Varnish are stored in /etc/default/varnish (Debian, Ubuntu) or
-/etc/sysconfig/varnish (Red Hat, Centos).
+If you run Varnish out of a package for your operating system,
+you will find the default options here:
 
-There are quite a few options you can tweak but most of you will only
-need to change a few them.
+* Debian, Ubuntu: /etc/default/varnish
+* Red Hat, Centos: /etc/sysconfig/varnish
+* FreeBSD: /etc/rc.conf (See also: /usr/local/etc/rc.d/varnishd)
 
-The typical command line options you want to change are:
+There some command line options you will simply have choose values for:
 
 -a *listen_address*
-    What address should Varnish listen to. The default is to listen to
-    all IP adresses and stick to port 80. ":80" will ask Varnish to
-    listen to all adresses, both IPv4 and IPv6 and is probably a
-    sensible thing.
+^^^^^^^^^^^^^^^^^^^
+
+What address should Varnish listen to and service HTTP requests on.
+
+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
+to open and service as many of them as possible, but if none of them
+can be opened, varnishd will not start.
+
+Here are some examples::
+
+	-a :80
+	-a localhost:80
+	-a 192.168.1.100:8080
+	-a '[fe80::1]:80'
+	-a '0.0.0.0:8080,[::]:8081'
+
+If your webserver runs on the same computer, you will have to move
+it to another port number first.
  
--f *config file*
-     The -f options specifies what VCL file Varnish should use as the default.
-
--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 *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.
+-f *VCL-file* or -b *backend*
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+Using -b is a quick way to get started::
+
+	-b localhost:81
+	-b thatotherserver.example.com:80
+	-b 192.168.1.2:80
+
+Notice that if you specify a name, it can at most resolve to one IPv4
+*and* one IPv6 address.
+
+If you go with -f, you can start with a VCL file containing just::
+
+	backend default {
+		.host = "localhost:81";
+	}
+
+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.
 
 For a complete list of the command line parameters please see
 :ref:`ref-varnishd-options`.

doc/sphinx/users-guide/run_security.rst

@@ -80,14 +80,17 @@ and give remote users access via a secure connection to the local
 machine (ssh, VPN, etc. etc.)
 
 It is also possible to configure varnishd for "reverse mode", using
-the '-M' argument,
-
-In this case varnishd will attempt to open a TCP connection to the
-specified address, and initiate a CLI connection on it.
+the '-M' argument.  In that case varnishd will attempt to open a
+TCP connection to the specified address, and initiate a CLI connection
+to your central varnish management facility.
 
 The connection is also in this case without secrecy, but if configured
 the remote end must still satisfy -S/PSK authentication.
 
+Finally, if you run varnishd with the '-d' option, you get a CLI
+command on stdin/stdout, but since you started the process, it
+would be hard to prevent you getting CLI access, wouldn't it ?
+
 Parameters
 ^^^^^^^^^^
 
@@ -130,7 +133,7 @@ We do not currently have a way to restrict specific CLI commands
 to specific CLI connections.   One way to get such an effect is to
 "wrap" all CLI access in pre-approved scripts which use varnishadm(1)
 to submit the sanitized CLI commands, and restrict a remote user
-to only those scripts in sshd(8)'s configuration.
+to only those scripts, for instance using sshd(8)'s configuration.
 
 VCL programs
 ------------
@@ -151,7 +154,7 @@ lower the privilege of a child process...
 Inline-C is disabled by default starting with Varnish 4, so unless
 you enable it, you don't have to worry about it.
 
-The params mentioned above can restrict VMOD so they can only
+The parameters mentioned above can restrict VMOD, so they can only
 be imported from a designated directory, restricting VCL wranglers
 to a pre-approved subset of VMODs.
 
@@ -171,7 +174,7 @@ to do exactly stupid things to them, including opening youself up
 to various kinds of attacks and subversive activities.
 
 If you have "administrative" HTTP requests, for instance PURGE
-requests, we recommend that you restrict them to trusted IP
-numbers/nets using VCL's Access Control Lists.
+requests, we strongly recommend that you restrict them to trusted
+IP numbers/nets using VCL's Access Control Lists.
 
 (XXX: missing ref to ACL)