[master] 39741c0 Document `-x optstring` and `--optstring`

[Dridi Boukelmoune]

commit 39741c03d0d6a1a0778591076994390c74a9fee1
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date:   Mon Oct 9 19:06:02 2017 +0200

    Document `-x optstring` and `--optstring`

diff --git a/doc/sphinx/users-guide/run_cli.rst b/doc/sphinx/users-guide/run_cli.rst
index d2789db..e0c23e3 100644
--- a/doc/sphinx/users-guide/run_cli.rst
+++ b/doc/sphinx/users-guide/run_cli.rst
@@ -169,3 +169,47 @@ 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.
+
+The shell, the other CLI
+------------------------
+
+Besides accessing the CLI via its interface or via ``varnishadm`` there
+is the matter of actually running the ``varnishd`` command line, usually
+via a shell. See :ref:`run_security` for security concerns around the
+``varnishd`` command line. See also :ref:`ref_syntax` about the CLI
+syntax and quoting pitfalls when using ``varnishadm``.
+
+The programs shipped with Varnish can expose their *optstring* in order
+to help writing wrapper scripts, in particular to get an opportunity to
+hook a task before a program daemonizes. With the exception of
+``varnishtest`` and ``varnishadm``, you can write Shell wrappers for
+``varnishd`` using the ``-x`` option and other programs using the
+``--optstring`` long option.
+
+This way, when writing a wrapper script you don't need to maintain the
+*optstring* in sync when you only need a subset of the options, usually
+``-n`` or ``-P``::
+
+    optstring=$(varnishd -x optstring)
+
+    while getopts "$optstring" opt
+    do
+        case $opt in
+        n)
+            # handle $OPTARG
+            ;;
+        # handle other options
+        *)
+            # ignore unneeded options
+            ;;
+        esac
+    done
+
+    varnishd "$@"
+
+    # do something with the options
+
+You can for example write a wrapper script that blocks until the shared
+memory is ready or when the child is started if you need that kind of
+synchronization. You can also prevent ``varnishd`` from starting if the
+``-S`` option is inadvertently set to not challenge access to the CLI.