[master] 28966bd Doc fixes

[Federico G. Schwindt]

commit 28966bd1d3105c0ac9af55924cf95228498fab17
Author: Federico G. Schwindt <fgsch at lodoss.net>
Date:   Tue Oct 13 05:07:37 2015 +0100

    Doc fixes
    
    From minusf via github with minor tweaks.

diff --git a/doc/sphinx/users-guide/run_security.rst b/doc/sphinx/users-guide/run_security.rst
index 41c68a8..2beb4aa 100644
--- a/doc/sphinx/users-guide/run_security.rst
+++ b/doc/sphinx/users-guide/run_security.rst
@@ -57,11 +57,9 @@ much anything the kernel will accept::
 	-T '[fe80::1]:8082'
 
 The default is ``-T localhost:0`` which will pick a random
-port number, which `varnishadm(8)` can learn in the shared
+port number, which `varnishadm(8)` can learn from the shared
 memory.
 
-.. XXX:Me no understand sentence above, (8)? and learn in the shared memory? Stored and retrieved by varnishadm from th e shared memory? benc 
-
 By using a "localhost" address, you restrict CLI access
 to the local machine.
 
@@ -77,9 +75,9 @@ Alternatively you can bind the CLI port to a 'localhost' address,
 and give remote users access via a secure connection to the local
 machine, using ssh/VPN or similar.
 
-If you use `ssh` you can restrict which commands each user can execute to
-just `varnishadm`, or even to wrapper scripts around `varnishadm`, which
-only allow specific CLI commands.
+If you use `ssh` you can restrict which commands each user can execute
+to just `varnishadm`, or even use a wrapper scripts around `varnishadm`
+to allow specific CLI commands.
 
 It is also possible to configure `varnishd` for "reverse mode", using
 the '-M' argument.  In that case `varnishd` will attempt to open a
@@ -99,11 +97,9 @@ would be hard to prevent you getting CLI access, wouldn't it ?
 CLI interface authentication
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-By default the CLI interface is protected with a simple, yet
-strong "Pre Shared Key" authentication method, which do not provide
-secrecy (ie: The CLI commands and responses are not encrypted).
-
-.. XXX:Encryption instead of secrecy? benc
+By default the CLI interface is protected with a simple, yet powerful
+"Pre Shared Key" authentication method, which do not provide secrecy
+(ie: The CLI commands and responses are not encrypted).
 
 The way -S/PSK works is really simple:  During startup a file is
 created with a random content and the file is only accessible to
@@ -111,18 +107,14 @@ the user who started `varnishd` (or the superuser).
 
 To authenticate and use a CLI connection, you need to know the
 contents of that file, in order to answer the cryptographic
-challenge `varnishd` issues. 
-
-
-(XXX: xref to algo in refman)
-.. XXX:Dunno what this is? benc
+challenge `varnishd` issues, see :ref:`ref_psk_auth`.
 
 `varnishadm` uses all of this to restrict access, it will only function,
 provided it can read the secret file.
 
-If you want to allow other users, local or remote, to be able to access CLI connections, you must create your
-own secret file and make it possible for (only!) these users to
-read it.
+If you want to allow other users, local or remote, to be able to access
+CLI connections, you must create your own secret file and make it possible
+for (only!) these users to read it.
 
 A good way to create the secret file is::
 
@@ -168,7 +160,7 @@ Furthermore you may want to look at and lock down:
 :ref:`ref_param_vcc_unsafe_path`
 	Restrict VCL/VMODS to :ref:`ref_param_vcl_dir` and :ref:`ref_param_vmod_dir`
 
-:ref:`ref_param_vmod_dir` 
+:ref:`ref_param_vmod_dir`
         The directory where Varnish will will look
         for modules. This could potentially be used to load rouge
         modules into Varnish.
@@ -188,13 +180,9 @@ 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)`
 
-.. XXX:what does the 1 stand for? benc
-
 to submit the sanitized CLI commands, and restrict a remote user
 to only those scripts, for instance using sshd(8)'s configuration.
 
-.. XXX:what does the 8 stand for? benc
-
 VCL programs
 ------------
 
@@ -214,9 +202,9 @@ lower the privilege of a child process...
 Inline-C is disabled by default starting with Varnish version 4, so unless
 you enable it, you don't have to worry about it.
 
-The parameters mentioned above can restrict the loading of VMODs to only 
-be loaded from a designated directory, restricting VCL wranglers
-to a pre-approved subset of VMODs.
+The parameters mentioned above can restrict the loading of VMODs to only
+be loaded from a designated directory, restricting VCL wranglers to a
+pre-approved subset of VMODs.
 
 If you do that, we are confident that your local system cannot be compromised
 from VCL code.