More doc-polish

doc/sphinx/reference/cli_protocol.rst

@@ -10,15 +10,15 @@ The Varnish CLI has a few bells&whistles when used as an API.
 
 First: `vcli.h` contains magic numbers.
 
-Second: If you use `varnishadm` to connect to `varnishd` use the
-`-p` argument to get "pass" mode.
+Second: If you use `varnishadm` to connect to `varnishd` for
+API purposes, use the `-p` argument to get "pass" mode.
 
 In "pass" mode, or with direct CLI connections (more below), the
 first line of responses is always exactly 13 bytes long, including
 the NL, and it contains two numbers:  The status code and the count
-of bytes in the remainder of the response::
+of bytes in the "body" of the response::
 
-    200␣19␤
+    200␣19␣␣␣␣␣␣␤
     PONG␣1613397488␣1.0
 
 This makes parsing the response unambiguous, even in cases like this
@@ -27,23 +27,63 @@ where the response does not end with a NL.
 The varnishapi library contains functions to implement the basics of
 the CLI protocol, for more, see the `vcli.h` include file.
 
+.. _ref_remote_cli:
+
+Local and remote CLI connections
+--------------------------------
+
+The ``varnishd`` process receives the CLI commands via TCP connections
+which require PSK authentication (see below), but which provide no secrecy.
+
+"No secrecy" means that if you configure these TCP connections to run
+across a network, anybody who can sniff packets can see your CLI
+commands.  If you need secrecy, use ``ssh`` to run ``varnishadm`` or
+to tunnel the TCP connection.
+
+By default `varnishd` binds to ``localhost`` and ask the kernel to
+assign a random port number.  The resulting listen address is
+stored in the shared memory, where the ``varnishadm`` program finds it.
+
+You can configure ``varnishd`` to listen to a specific address with
+the ``-T`` argument, this will also be written to shared memory, so
+``varnishadm`` keeps working::
+
+	# Bind to internal network
+	varnishd -T 192.168.10.21:3245
+
+You can also configure ``varnishd`` to actively open a TCP connection
+to another "controller" program, with the ``-M`` argument.
+
+Finally, when run in "debug mode" with the ``-d`` argument, ``varnishd``
+will stay in the foreground and turn stdin/stdout into a CLI connection.
+
 .. _ref_psk_auth:
 
 Authentication CLI connections
 ------------------------------
 
 CLI connections to `varnishd` are authenticated with a "pre-shared-key"
-authentication scheme, where the other end must prove they know the
-contents of a particular file, either by being able to access it on
-the machine `varnishd` runs on, usually via information in `VSM` or
-by having a local copy of the file on another machine.
+authentication scheme, where the other end must prove they know
+*the contents of* the secret file ``varnishd`` uses.
+
+They do not have to read the precise same file on that specific
+computer, they could read an entirely different file on a different
+computer or fetch the secret from a server.
+
+The name of the file can be configured with the ``-S`` option, and
+``varnishd`` records the name in shared memory, so ``varnishadm``
+can find it.
+
+As a bare minimum ``varnishd`` needs to be able to read the file,
+but other than that, it can be restricted any way you want.
 
-The precise filename can be configured with the `-S` option to `varnishd`
-and regular file system permissions control access to it.
+Since it is not the file, but only the content of it that matter,
+you can make the file unreadable by everybody, and instead place
+a copy of the file in the home directories of the authorized users.
 
-The file is only read at the time the `auth` CLI command is issued
-and the contents is not cached in `varnishd`, so it is possible to
-change the contents of the file while `varnishd` is running.
+The file is read only at the moment when the `auth` CLI command is
+issued and the contents is not cached in `varnishd`, so you can
+change it as often as you want.
 
 An authenticated session looks like this:
 
@@ -77,7 +117,7 @@ first 32 characters of the response text is the challenge
 connection, and changes each time a 107 is emitted.
 
 The most recently emitted challenge must be used for calculating the
-authenticator "455c...c89a".
+authenticator "455c…c89a".
 
 The authenticator is calculated by applying the SHA256 function to the
 following byte sequence:
@@ -110,7 +150,7 @@ In the above example, the secret file contains ``foo\n`` and thus:
    00000040  66 79 6d 70 67 0a                                 |fympg.|
    00000046
    critter phk> sha256 tmpfile
-   SHA256 (_) = 455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a
+   SHA256 (tmpfile) = 455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a
    critter phk> openssl dgst -sha256 < tmpfile
    455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a
 

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

 .. _users-guide-command-line:
 
-Important command line arguments
---------------------------------
+Required command line arguments
+-------------------------------
 
 There a two command line arguments you have to set when starting Varnish, these are:
 * what TCP port to serve HTTP from, and
@@ -44,7 +44,6 @@ it to another port number first.
 '-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 the '-b' argument, or you can put it in your own VCL file, specified with the '-f' argument.
 
@@ -57,37 +56,17 @@ Using '-b' is a quick way to get started::
 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::
+For more advanced use, you will want to specify a VCL program with ``-f``,
+but you can start with as little as just::
 
 	backend default {
 		.host = "localhost:81";
 	}
 
-which is exactly what '-b' does.
-
-.. XXX:What happens if I start with -b and then have the backend defined in my VCL? benc
-
-In both cases the built-in VCL code is appended.
-
-Other options
-^^^^^^^^^^^^^
-
-Varnish comes with an abundance of useful command line arguments. We recommend that you study them but not necessary use them all, but to get started, the above will be sufficient.
-
-By default Varnish will use 100 megabytes of virtual memory (malloc(3)
-or libumem(3lib)) storage for caching objects, if you want to cache
-more than that, you should look at the '-s' argument.
-
-.. XXX: 3? benc
-
-If you run a really big site, you may want to tune the number of
-worker threads and other parameters with the '-p' argument,
-but we generally advice not to do that unless you need to.
+which is, by the way, *precisely* what '-b' does.
 
-Before you go into production, you may also want to revisit the
-chapter
-:ref:`run_security` to see if you need to partition administrative
-privileges.
+Optional arguments
+^^^^^^^^^^^^^^^^^^
 
-For a complete list of the command line parameters please see
-:ref:`ref-varnishd-options`.
+For a complete list of the command line arguments please see
+:ref:`varnishd(1) options <ref-varnishd-options>`.

doc/sphinx/users-guide/run_cli.rst

@@ -3,46 +3,54 @@
 CLI - bossing Varnish around
 ============================
 
-Once ``varnishd`` is started, you can control it using the command line
-interface.
-
-The easiest way to do this, is using ``varnishadm`` on the
-same machine as ``varnishd`` is running::
+Once ``varnishd`` is started, you can control it using the ``varnishadm``
+program and the command line interface::
 
 	varnishadm help
 
-If you want to run ``varnishadm`` from a remote system, you can do it
-two ways.
+If you want to run ``varnishadm`` from a remote system, we recommend
+you use ``ssh`` into the system where ``varnishd`` runs. (But see also:
+:ref:`Local and remote CLI connections <ref_remote_cli>`)
 
 You can SSH into the ``varnishd`` computer and run ``varnishadm``::
 
-	ssh $http_front_end varnishadm help
-
-But you can also configure ``varnishd`` to accept remote CLI connections
-(using the '-T' and '-S' arguments)::
+	ssh $hostname varnishadm help
 
-	varnishd -T :6082 -S /etc/varnish_secret
+If you give no command arguments, ``varnishadm`` runs in interactive mode
+with command-completion, command-history and other comforts:
 
-And then on the remote system run ``varnishadm``::
+.. code-block:: text
 
-	varnishadm -T $http_front_end -S /etc/copy_of_varnish_secret help
+    critter phk> ./varnishadm 
+    200        
+    -----------------------------
+    Varnish Cache CLI 1.0
+    -----------------------------
+    FreeBSD,13.0-CURRENT,amd64,-jnone,-sdefault,-sdefault,-hcritbit
+    varnish-trunk revision 2bd5d2adfc407216ebaa653fae882d3c8d47f5e1
+    
+    Type 'help' for command list.
+    Type 'quit' to close CLI session.
+    Type 'start' to launch worker process.
+    
+    varnish> 
 
-but as you can see, SSH is much more convenient.
+The CLI always returns a three digit status code to tell how things went.
 
-If you run ``varnishadm`` without arguments, it will read CLI commands from
-``stdin``, if you give it arguments, it will treat those as the single
-CLI command to execute.
+200 and 201 means *OK*, anything else means that some kind of trouble
+prevented the execution of the command.
 
-The CLI always returns a status code to tell how it went:  '200'
-means OK, anything else means there were some kind of trouble.
+(If you get 201, it means that the output was truncated,
+See the :ref:`ref_param_cli_limit` parameter.)
 
-``varnishadm`` will exit with status 1 and print the status code on
-standard error if it is not 200.
+When commands are given as arguments to ``varnishadm``, a status
+different than 200 or 201 will cause it to exit with status 1
+and print the status code on standard error.
 
 What can you do with the CLI
 ----------------------------
 
-The CLI gives you almost total control over ``varnishd`` some of the more important tasks you can perform are:
+From the CLI you can:
 
 * load/use/discard VCL programs
 * ban (invalidate) cache content
@@ -91,19 +99,18 @@ The switch is instantaneous, all new requests will start using the
 VCL you activated right away. The requests currently being processed complete
 using whatever VCL they started with.
 
-It is good idea to design an emergency-VCL before you need it,
-and always have it loaded, so you can switch to it with a single
-vcl.use command.
+We highly recommend you design an emergency-VCL, and always keep
+it loaded, so it can be activated with ::
 
-.. XXX:Should above have a clearer admonition like a NOTE:? benc
+	vcl.use emergency
 
 Ban cache content
 ^^^^^^^^^^^^^^^^^
 
-Varnish offers "purges" to remove things from cache, provided that
-you know exactly what they are.
+Varnish offers "purges" to remove things from cache, but that
+requires you to know exactly what they are.
 
-But sometimes it is useful to be able to throw things out of cache
+Sometimes it is useful to be able to throw things out of cache
 without having an exact list of what to throw out.
 
 Imagine for instance that the company logo changed and now you need
@@ -116,14 +123,13 @@ Varnish to stop serving the old logo out of the cache:
 should do that, and yes, that is a regular expression.
 
 We call this "banning" because the objects are still in the cache,
-but they are banned from delivery.
+but they are now banned from delivery, while all the rest of the
+cache is unaffected.
 
-Instead of checking each and every cached object right away, we
-test each object against the regular expression only if and when
-an HTTP request asks for it.
+Even when you want to throw out *all* the cached content, banning is
+both faster and less disruptive that a restart::
 
-Banning stuff is much cheaper than restarting Varnish to get rid
-of wronly cached content.
+	varnish> ban obj.http.date ~ .*
 
 .. In addition to handling such special occasions, banning can be used
 .. in many creative ways to keep the cache up to date, more about
@@ -134,7 +140,8 @@ Change parameters
 ^^^^^^^^^^^^^^^^^
 
 Parameters can be set on the command line with the '-p' argument,
-but they can also be examined and changed on the fly from the CLI:
+but almost all parameters can be examined and changed on the fly
+from the CLI:
 
 .. code-block:: text
 
@@ -153,10 +160,10 @@ have a good reason, such as performance tuning or security configuration.
 
 .. XXX: Natural delay of some duration sounds vague. benc
 
-Most parameters will take effect instantly, or with a natural delay
-of some duration, but a few of them requires you to restart the
-child process before they take effect. This is always noted in the
-description of the parameter.
+Most parameters will take effect instantly, or with a short delay,
+but a few of them requires you to restart the child process before
+they take effect. This is always mentioned in the description of
+the parameter.
 
 Starting and stopping the worker process
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -174,4 +181,5 @@ If you start ``varnishd`` with the '-d' (debugging) argument, you will
 always need to start the child process explicitly.
 
 Should the child process die, the master process will automatically
-restart it, but you can disable that with the 'auto_restart' parameter.
+restart it, but you can disable that with the
+:ref:`ref_param_auto_restart` parameter.