[master] 10ac7e1 Explain what may go wrong with quoting and the CLI
Dridi Boukelmoune
dridi.boukelmoune at gmail.com
Tue Nov 8 16:30:06 CET 2016
commit 10ac7e1f480a7382c8fd12eb30193b7aff349847
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date: Tue Nov 8 15:43:06 2016 +0100
Explain what may go wrong with quoting and the CLI
Fixes #1899
Closes #2110
diff --git a/doc/sphinx/reference/varnish-cli.rst b/doc/sphinx/reference/varnish-cli.rst
index c0c911a..58c80ef 100644
--- a/doc/sphinx/reference/varnish-cli.rst
+++ b/doc/sphinx/reference/varnish-cli.rst
@@ -94,6 +94,86 @@ When using the here document style of input there are no restrictions
on length. When using newline-terminated commands maximum length is
limited by the varnishd parameter *cli_buffer*.
+Quoting pitfalls
+----------------
+
+Integrating with the Varnish CLI can be sometimes surprising when quoting
+is involved. For instance in Bourne Shell the delimiter used with here
+documents may or may not be separated by spaces from the ``<<`` token::
+
+ cat <<EOF
+ hello
+ world
+ EOF
+ hello
+ world
+
+With the Varnish CLI, the ``<<`` and ``EOF`` tokens must be separated by
+at least one blank::
+
+ vcl.inline boot <<EOF
+ 106 258
+ Message from VCC-compiler:
+ VCL version declaration missing
+ Update your VCL to Version 4 syntax, and add
+ vcl 4.0;
+ on the first line of the VCL files.
+ ('<vcl.inline>' Line 1 Pos 1)
+ <<EOF
+ ##---
+
+ Running VCC-compiler failed, exited with 2
+ VCL compilation failed
+
+With the missing space, the here document can be added and the actual VCL
+can be loaded::
+
+ vcl.inline test << EOF
+ vcl 4.0;
+
+ backend be {
+ .host = "localhost";
+ }
+ EOF
+ 200 14
+ VCL compiled.
+
+When using a front-end to the Varnish-CLI like ``varnishadm``, one must
+take into account the double expansion happening. First in the shell
+launching the ``varnishadm`` command and then in the Varnish CLI itself.
+When a command's parameter require spaces, you need to ensure that the
+Varnish CLI will see the double quotes::
+
+ varnishadm param.set cc_command '"my alternate cc command"'
+
+ Change will take effect when VCL script is reloaded
+
+Otherwise if you don't quote the quotes, you may get a seemingly unrelated
+error message::
+
+ varnishadm param.set cc_command "my alternate cc command"
+ Unknown request.
+ Type 'help' for more info.
+ Too many parameters
+
+ Command failed with error code 105
+
+If you are quoting with a here document, you must wrap it inside a shell
+multi-line argument::
+
+ varnishadm vcl.inline test '<< EOF
+ vcl 4.0;
+
+ backend be {
+ .host = "localhost";
+ }
+ EOF'
+ VCL compiled.
+
+Other pitfalls include variable expansion of the shell invoking ``varnishadm``
+but this is not directly related to the Varnish CLI. If you get the quoting
+right you should be fine even with complex commands.
+
Commands
--------
More information about the varnish-commit
mailing list