It's a getopt interface and we're not using getopt, at least directly, so even though it works relying on it feels wrong. GOption takes care of removing any trace of the arguments it consumes from argc and argv, leaving behind only non-option arguments, so we can just use those standard variables. Signed-off-by: Andrea Bolognani <abologna(a)redhat.com&gt; --- src/remote/remote_ssh_helper.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/remote/remote_ssh_helper.c b/src/remote/remote_ssh_helper.c index 0945b90331..092676dd74 100644 --- a/src/remote/remote_ssh_helper.c +++ b/src/remote/remote_ssh_helper.c @@ -395,12 +395,12 @@ int main(int argc, char **argv) /* Initialize the log system */ virLogSetFromEnv(); - if (optind != (argc - 1)) { + if (argc != 2) { g_printerr("%s: expected a URI\n", argv[0]); exit(EXIT_FAILURE); } - uri_str = argv[optind]; + uri_str = argv[1]; VIR_DEBUG("Using URI %s", uri_str); if (!(uri = virURIParse(uri_str))) { -- 2.31.1

Specifically: * include non-option argument 'URI' in usage summary; * mention that it's an internal tool not meant to be called directly; * exit earlier if required arguments are absent. Signed-off-by: Andrea Bolognani <abologna(a)redhat.com&gt; --- src/remote/remote_ssh_helper.c | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/src/remote/remote_ssh_helper.c b/src/remote/remote_ssh_helper.c index 092676dd74..4f4dbff7d0 100644 --- a/src/remote/remote_ssh_helper.c +++ b/src/remote/remote_ssh_helper.c @@ -369,7 +369,10 @@ int main(int argc, char **argv) }; unsigned int flags; - context = g_option_context_new("- libvirt socket proxy"); + context = g_option_context_new("URI - libvirt socket proxy"); + g_option_context_set_summary(context, + "Internal tool used to handle connections coming from remote\n" + "clients. Not intended to be called directly by the user."); g_option_context_add_main_entries(context, entries, PACKAGE); if (!g_option_context_parse(context, &argc, &argv, &error)) { g_printerr(_("option parsing failed: %s\n"), error->message); @@ -381,6 +384,12 @@ int main(int argc, char **argv) exit(EXIT_SUCCESS); } + if (argc != 2) { + g_autofree char *help = g_option_context_get_help(context, TRUE, NULL); + g_printerr("%s", help); + exit(EXIT_FAILURE); + } + virSetErrorFunc(NULL, NULL); virSetErrorLogPriorityFunc(NULL); @@ -395,11 +404,6 @@ int main(int argc, char **argv) /* Initialize the log system */ virLogSetFromEnv(); - if (argc != 2) { - g_printerr("%s: expected a URI\n", argv[0]); - exit(EXIT_FAILURE); - } - uri_str = argv[1]; VIR_DEBUG("Using URI %s", uri_str); -- 2.31.1

Signed-off-by: Andrea Bolognani <abologna(a)redhat.com&gt; --- docs/manpages/meson.build | 1 + docs/manpages/virt-ssh-helper.rst | 96 +++++++++++++++++++++++++++++++ libvirt.spec.in | 1 + 3 files changed, 98 insertions(+) create mode 100644 docs/manpages/virt-ssh-helper.rst diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build index cafe29a545..e80fff48c8 100644 --- a/docs/manpages/meson.build +++ b/docs/manpages/meson.build @@ -18,6 +18,7 @@ docs_man_files = [ { 'name': 'virt-login-shell', 'section': '1', 'install': conf.has('WITH_LOGIN_SHELL') }, { 'name': 'virt-pki-validate', 'section': '1', 'install': true }, { 'name': 'virt-qemu-run', 'section': '1', 'install': conf.has('WITH_QEMU') }, + { 'name': 'virt-ssh-helper', 'section': '1', 'install': true }, { 'name': 'virt-xml-validate', 'section': '1', 'install': true }, { 'name': 'libvirtd', 'section': '8', 'install': conf.has('WITH_LIBVIRTD') }, diff --git a/docs/manpages/virt-ssh-helper.rst b/docs/manpages/virt-ssh-helper.rst new file mode 100644 index 0000000000..be3f7db243 --- /dev/null +++ b/docs/manpages/virt-ssh-helper.rst @@ -0,0 +1,96 @@ +=============== +virt-ssh-helper +=============== + +-------------------- +libvirt socket proxy +-------------------- + +:Manual section: 1 +:Manual group: Virtualization Support + +.. contents:: + + +SYNOPSIS +======== + +``virt-ssh-helper`` [*OPTIONS*...] *URI* +``virt-ssh-helper`` *OPTION* + + +DESCRIPTION +=========== + +``virt-ssh-helper`` is an internal tool used to handle connections +coming from remote clients, and it's not intended to be called +directly by the user. + + +OPTIONS +======= + +*URI* + +Local libvirt URI to connect the remote client to. + +``-r``, ``--readonly`` + +Make the connection read-only. + +``-h``, ``--help`` + +Display command line help usage then exit. + +``-V``, ``--version`` + +Display version information then exit. + + +EXIT STATUS +=========== + +The exit status will be zero on success, non-zero on failure. + + +AUTHOR +====== + +Daniel P. Berrangé + + +BUGS +==== + +Please report all bugs you discover. This should be done via either: + +#. the mailing list + + `https://libvirt.org/contact.html <https://libvirt.org/contact.html>`_ + +#. the bug tracker + + `https://libvirt.org/bugs.html <https://libvirt.org/bugs.html>`_ + +Alternatively, you may report bugs to your software distributor / vendor. + + +COPYRIGHT +========= + +Copyright (C) 2020 Red Hat, Inc. + + +LICENSE +======= + +``virt-ssh-helper`` is distributed under the terms of the GNU LGPL v2+. +This is free software; see the source for copying conditions. There +is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR +PURPOSE. + + +SEE ALSO +======== + +virsh(1), `https://libvirt.org/ <https://libvirt.org/>`_ diff --git a/libvirt.spec.in b/libvirt.spec.in index 5a079cdaf3..9cf1046604 100644 --- a/libvirt.spec.in +++ b/libvirt.spec.in @@ -1697,6 +1697,7 @@ exit 0 %{_mandir}/man1/virt-admin.1* %{_mandir}/man1/virt-host-validate.1* +%{_mandir}/man1/virt-ssh-helper.1* %{_mandir}/man8/libvirtd.8* %{_mandir}/man8/virtlogd.8* %{_mandir}/man8/virtlockd.8* -- 2.31.1

Specifically, include non-option argument 'GUEST-XML-FILE' in usage summary. Signed-off-by: Andrea Bolognani <abologna(a)redhat.com&gt; --- src/qemu/qemu_shim.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/qemu/qemu_shim.c b/src/qemu/qemu_shim.c index 8b3afd0324..a06869a406 100644 --- a/src/qemu/qemu_shim.c +++ b/src/qemu/qemu_shim.c @@ -163,7 +163,7 @@ int main(int argc, char **argv) #define deltams() ((long long)g_get_monotonic_time() - start) - ctx = g_option_context_new("- run a standalone QEMU process"); + ctx = g_option_context_new("GUEST-XML-FILE - run a standalone QEMU process"); g_option_context_add_main_entries(ctx, entries, PACKAGE); if (!g_option_context_parse(ctx, &argc, &argv, &error)) { g_printerr("%s: option parsing failed: %s\n", -- 2.31.1

Specifically: * use the correct notation and markup for commands, options and arguments; * rename arguments meta-variables; * document '--help' and '--version' options; * use consistent vertical spacing; * fix a typo. Signed-off-by: Andrea Bolognani <abologna(a)redhat.com&gt; --- docs/manpages/virt-qemu-run.rst | 53 +++++++++++++++++++-------------- 1 file changed, 31 insertions(+), 22 deletions(-) diff --git a/docs/manpages/virt-qemu-run.rst b/docs/manpages/virt-qemu-run.rst index 470de93168..a755b7fda9 100644 --- a/docs/manpages/virt-qemu-run.rst +++ b/docs/manpages/virt-qemu-run.rst @@ -11,10 +11,13 @@ Run a standalone QEMU guest .. contents:: + SYNOPSIS ======== -``virt-qemu-run [OPTIONS...] [GUEST-XML]`` +``virt-qemu-run`` [*OPTIONS...*] *GUEST-XML-FILE* +``virt-qemu-run`` *OPTION* + DESCRIPTION =========== @@ -26,50 +29,54 @@ directory tree. When the guest is run with this tool it is invisible to libvirtd and thus also invisible to other libvirt tools such as virsh. -The virt-qemu-run program will run the QEMU virtual machine, and then -block until the guest OS shuts down, at which point it will exit. +The ``virt-qemu-run`` program will run the QEMU virtual machine, and +then block until the guest OS shuts down, at which point it will +exit. -If the virt-qemu-run program is interrupted (eg Ctrl-C) it will -immediately terminate the virtual machine without giving the guest -OS any opportunity to gracefully shutdown. +If the ``virt-qemu-run`` program is interrupted (eg Ctrl-C) it will +immediately terminate the virtual machine without giving the guest OS +any opportunity to gracefully shutdown. **NOTE: this tool is currently considered experimental.** Its usage and behaviour is still subject to change in future libvirt releases. For further information on its usage consult the `QEMU driver documentation <https://libvirt.org/drvqemu.html#embedded-driver>`_. + OPTIONS ======= -``GUEST-XML`` +*GUEST-XML-FILE* The full path to the XML file describing the guest virtual machine to be booted. -``-h``, ``--help`` - -Display the command line help - -``-v``, ``--verbose`` - -Display verbose information about startup - -``-r DIR``, ``--root=DIR`` +``-r`` *DIR*, ``--root``\ =\ *DIR* Specify the root directory to use for storing state associated with the virtual machine. The caller is responsible for deleting this directory when it is no longer required. If this parameter is omitted, then a random temporary directory -will be created, and its contents be automaticlaly deleted at +will be created, and its contents be automatically deleted at VM shutdown. -``-s XML-FILE,VALUE-FILE``, ``--secret=XML-FILE,VALUE-FILE`` +``-s`` *SECRET-XML-FILE*\ ,\ *SECRET-VALUE-FILE*, +``--secret``\ =\ *SECRET-XML-FILE*\ ,\ *SECRET-VALUE-FILE* + +Specify a secret to be loaded into the secret driver. +*SECRET-XML-FILE* is a path to the XML description of the secret, +whose UUID should match a secret referenced in the guest domain XML. +*SECRET-VALUE-FILE* is a path containing the raw value of the secret. + +``-h``, ``--help`` + +Display the command line help + +``-v``, ``--verbose`` + +Display verbose information about startup -Specify a secret to be loaded into the secret driver. The ``XML-FILE`` -is a path to the XML description of the secret, whose UUID should -match a secret referenced in the guest domain XML. The ``VALUE-FILE`` -is a path containing the raw value of the secret. EXIT STATUS =========== @@ -77,6 +84,7 @@ EXIT STATUS Upon successful shutdown, an exit status of 0 will be set. Upon failure a non-zero status will be set. + AUTHOR ====== @@ -113,6 +121,7 @@ This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE + SEE ALSO ======== -- 2.31.1

On a Friday in 2021, Andrea Bolognani wrote: Same issue as with virt-qemu-run man page. Reviewed-by: Ján Tomko <jtomko(a)redhat.com&gt; Jano