[master] ac0b9f5ac Teach the remaining programs about --optstring.

Poul-Henning Kamp phk at FreeBSD.org
Mon Feb 22 12:27:09 UTC 2021


commit ac0b9f5ac4e2c932ad0f6983584fbc7a4b2440de
Author: Poul-Henning Kamp <phk at FreeBSD.org>
Date:   Mon Feb 22 10:32:30 2021 +0000

    Teach the remaining programs about --optstring.
    
    Move the description of this feature from user to reference.

diff --git a/bin/varnishadm/varnishadm.c b/bin/varnishadm/varnishadm.c
index 76b19e775..08c4a4125 100644
--- a/bin/varnishadm/varnishadm.c
+++ b/bin/varnishadm/varnishadm.c
@@ -423,6 +423,8 @@ n_arg_sock(const char *n_arg, const char *t_arg)
 	return (sock);
 }
 
+#define OPTARG "hn:pS:T:t:"
+
 int
 main(int argc, char * const *argv)
 {
@@ -432,6 +434,10 @@ main(int argc, char * const *argv)
 	const char *t_arg = NULL;
 	int opt, sock;
 
+	if (argc == 2 && !strcmp(argv[1], "--optstring")) {
+		printf(OPTARG "\n");
+		exit(0);
+	}
 	/*
 	 * By default linux::getopt(3) mangles the argv order, such that
 	 *	varnishadm -n bla param.set foo -bar
@@ -440,7 +446,7 @@ main(int argc, char * const *argv)
 	 * The '+' stops that from happening
 	 * See #1496
 	 */
-	while ((opt = getopt(argc, argv, "+hn:pS:T:t:")) != -1) {
+	while ((opt = getopt(argc, argv, "+" OPTARG)) != -1) {
 		switch (opt) {
 		case 'h':
 			/* Usage help */
diff --git a/bin/varnishd/mgt/mgt_main.c b/bin/varnishd/mgt/mgt_main.c
index 64e404c88..9f4c23623 100644
--- a/bin/varnishd/mgt/mgt_main.c
+++ b/bin/varnishd/mgt/mgt_main.c
@@ -490,6 +490,11 @@ main(int argc, char * const *argv)
 	struct vsb *vsb;
 	pid_t pid;
 
+	if (argc == 2 && !strcmp(argv[1], "--optstring")) {
+		printf("%s\n", opt_spec);
+		exit(0);
+	}
+
 	heritage.argc = argc;
 	heritage.argv = argv;
 
diff --git a/doc/sphinx/reference/index.rst b/doc/sphinx/reference/index.rst
index 58f6f7a93..fa6d61193 100644
--- a/doc/sphinx/reference/index.rst
+++ b/doc/sphinx/reference/index.rst
@@ -88,12 +88,13 @@ Varnishtest
 	VarnishTest - execute test cases <varnishtest>
 	vmod_vtc.rst
 
-For Developers
---------------
+For Developers & DevOps
+-----------------------
 
 .. toctree::
 	:maxdepth: 1
 
+	Shell tricks <shell_tricks>
 	VMODS - Extensions to VCL <vmod>
 	VSM - Shared memory use <vsm>
 	VDIR - Backends & Directors <directors>
diff --git a/doc/sphinx/reference/shell_tricks.rst b/doc/sphinx/reference/shell_tricks.rst
new file mode 100644
index 000000000..471706575
--- /dev/null
+++ b/doc/sphinx/reference/shell_tricks.rst
@@ -0,0 +1,30 @@
+.. _ref-shell_tricks:
+
+%%%%%%%%%%%%
+Shell Tricks 
+%%%%%%%%%%%%
+
+All the varnish programs can be invoked with the single
+argument ``--optstring`` to request their `getopt()`
+specification, which simplifies wrapper scripts:
+
+.. code-block:: shell
+
+    optstring=$(varnishfoo --optstring)
+
+    while getopts "$optstring" opt
+    do
+        case $opt in
+        n)
+            # handle $OPTARG
+            ;;
+        # handle other options
+        *)
+            # ignore unneeded options
+            ;;
+        esac
+    done
+
+    varnishfoo "$@"
+
+    # do something with the options
diff --git a/doc/sphinx/users-guide/run_cli.rst b/doc/sphinx/users-guide/run_cli.rst
index e0c23e303..f68d0ffd2 100644
--- a/doc/sphinx/users-guide/run_cli.rst
+++ b/doc/sphinx/users-guide/run_cli.rst
@@ -65,7 +65,9 @@ To load new VCL program::
 	varnish> vcl.load some_name some_filename
 
 Loading will read the VCL program from the file, and compile it. If
-the compilation fails, you will get an error messages::
+the compilation fails, you will get an error messages:
+
+.. code-block:: text
 
 	.../mask is not numeric.
 	('input' Line 4 Pos 17)
@@ -105,7 +107,9 @@ But 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
-Varnish to stop serving the old logo out of the cache::
+Varnish to stop serving the old logo out of the cache:
+
+.. code-block:: text
 
 	varnish> ban req.url ~ "logo.*[.]png"
 
@@ -130,7 +134,9 @@ 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 they can also be examined and changed on the fly from the CLI:
+
+.. code-block:: text
 
 	varnish> param.show prefer_ipv6
 	200
@@ -169,47 +175,3 @@ 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.
diff --git a/doc/sphinx/users-guide/run_security.rst b/doc/sphinx/users-guide/run_security.rst
index 9d847df6b..8334eb8cd 100644
--- a/doc/sphinx/users-guide/run_security.rst
+++ b/doc/sphinx/users-guide/run_security.rst
@@ -199,7 +199,7 @@ system, but if `varnishd` is not started as root/superuser, this is
 not possible. No, don't ask me why you have to be superuser to
 lower the privilege of a child process...
 
-Inline-C is disabled by default starting with Varnish version 4, so unless
+Inline-C is disabled by default since 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


More information about the varnish-commit mailing list