[libvirt PATCH v2 0/1] Improve usage information and manual pages
Changes from [v1]: * the commit message has been updated to include the rationale for adding a manual page for virt-ssh-helper. [v1] https://listman.redhat.com/archives/libvir-list/2021-December/msg00466.html Andrea Bolognani (1): virt-ssh-helper: Add manual page docs/manpages/meson.build | 1 + docs/manpages/virt-ssh-helper.rst | 95 +++++++++++++++++++++++++++++++ libvirt.spec.in | 1 + 3 files changed, 97 insertions(+) create mode 100644 docs/manpages/virt-ssh-helper.rst -- 2.31.1
We don't usually provide manual pages for internal tools, but in the case of virt-ssh-helper the command is installed inside the default $PATH and so it's likely that the user will stumble upon it by using the shell's completion feature when invoking another virt-* command, which makes it a good idea to provide at least a minimal manual page. Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/manpages/meson.build | 1 + docs/manpages/virt-ssh-helper.rst | 95 +++++++++++++++++++++++++++++++ libvirt.spec.in | 1 + 3 files changed, 97 insertions(+) create mode 100644 docs/manpages/virt-ssh-helper.rst diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build index d8077f0b61..bf6fc730e0 100644 --- a/docs/manpages/meson.build +++ b/docs/manpages/meson.build @@ -19,6 +19,7 @@ docs_man_files = [ { 'name': 'virt-pki-query-dn', 'section': '1', 'install': true }, { '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..175ddacaec --- /dev/null +++ b/docs/manpages/virt-ssh-helper.rst @@ -0,0 +1,95 @@ +=============== +virt-ssh-helper +=============== + +-------------------- +libvirt socket proxy +-------------------- + +:Manual section: 1 +:Manual group: Virtualization Support + +.. contents:: + + +SYNOPSIS +======== + +``virt-ssh-helper`` [*OPTION*]... *URI* + + +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 32b4243d0a..352908642c 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
On 12/13/21 14:44, Andrea Bolognani wrote:
We don't usually provide manual pages for internal tools, but in the case of virt-ssh-helper the command is installed inside the default $PATH and so it's likely that the user will stumble upon it by using the shell's completion feature when invoking another virt-* command, which makes it a good idea to provide at least a minimal manual page.
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/manpages/meson.build | 1 + docs/manpages/virt-ssh-helper.rst | 95 +++++++++++++++++++++++++++++++ libvirt.spec.in | 1 + 3 files changed, 97 insertions(+) create mode 100644 docs/manpages/virt-ssh-helper.rst
Reviewed-by: Michal Privoznik <mprivozn@redhat.com> Michal
On Fri, Jan 07, 2022 at 04:30:33PM +0100, Michal Prívozník wrote:
On 12/13/21 14:44, Andrea Bolognani wrote:
We don't usually provide manual pages for internal tools, but in the case of virt-ssh-helper the command is installed inside the default $PATH and so it's likely that the user will stumble upon it by using the shell's completion feature when invoking another virt-* command, which makes it a good idea to provide at least a minimal manual page.
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/manpages/meson.build | 1 + docs/manpages/virt-ssh-helper.rst | 95 +++++++++++++++++++++++++++++++ libvirt.spec.in | 1 + 3 files changed, 97 insertions(+) create mode 100644 docs/manpages/virt-ssh-helper.rst
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
I just realized that there is a small bug in the patch: virt-ssh-helper is only built and installed when the daemon is, and obviously the same should happen to its manual page. I have squashed in the diff below before pushing. Thanks for the review! :) diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build index bf6fc730e0..6763d19af8 100644 --- a/docs/manpages/meson.build +++ b/docs/manpages/meson.build @@ -19,7 +19,7 @@ docs_man_files = [ { 'name': 'virt-pki-query-dn', 'section': '1', 'install': true }, { '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-ssh-helper', 'section': '1', 'install': conf.has('WITH_LIBVIRTD') }, { 'name': 'virt-xml-validate', 'section': '1', 'install': true }, { 'name': 'libvirtd', 'section': '8', 'install': conf.has('WITH_LIBVIRTD') }, -- Andrea Bolognani / Red Hat / Virtualization
Mon, 13 Dec 2021 14:44:51 +0100 Andrea Bolognani <abologna@redhat.com>:
+``virt-ssh-helper`` is an internal tool
If it is indeed an internal tool, why is the man page in section 1, and why is it in PATH? I think the man page needs to be moved to section 8, the binary into $libexec. The path to it will be known, the shell code from virNetClientSSHHelperCommand could be removed. There would be no requirement for which.rpm, which is also not noted as Requires in libvirt.spec. Olaf
On Mon, Jan 10, 2022 at 01:29:54PM +0100, Olaf Hering wrote:
Mon, 13 Dec 2021 14:44:51 +0100 Andrea Bolognani <abologna@redhat.com>:
+``virt-ssh-helper`` is an internal tool
If it is indeed an internal tool, why is the man page in section 1, and why is it in PATH? I think the man page needs to be moved to section 8, the binary into $libexec. The path to it will be known, the shell code from virNetClientSSHHelperCommand could be removed.
The path to the helper cannot be hardcoded, and it needs to be in $PATH, because the shell snippet is generated on the client side but executed on the server side. The two could have been configured with different prefixes, as is going to be the case for example when a macOS client connects to a Linux server.
There would be no requirement for which.rpm, which is also not noted as Requires in libvirt.spec.
This does indeed look like a bug. -- Andrea Bolognani / Red Hat / Virtualization
On Mon, Jan 10, 2022 at 01:02:43PM +0000, Andrea Bolognani wrote:
On Mon, Jan 10, 2022 at 01:29:54PM +0100, Olaf Hering wrote:
Mon, 13 Dec 2021 14:44:51 +0100 Andrea Bolognani <abologna@redhat.com>:
+``virt-ssh-helper`` is an internal tool
If it is indeed an internal tool, why is the man page in section 1, and why is it in PATH? I think the man page needs to be moved to section 8, the binary into $libexec. The path to it will be known, the shell code from virNetClientSSHHelperCommand could be removed.
The path to the helper cannot be hardcoded, and it needs to be in $PATH, because the shell snippet is generated on the client side but executed on the server side. The two could have been configured with different prefixes, as is going to be the case for example when a macOS client connects to a Linux server.
About the section. You might be right that 8 is a better fit than 1, but sections are somewhat loosely defined and I can't quite make up my mind about it. I'm definitely open to moving it if you can make a convincing enough case for it :) -- Andrea Bolognani / Red Hat / Virtualization
Mon, 10 Jan 2022 13:29:28 +0000 Andrea Bolognani <abologna@redhat.com>:
I'm definitely open to moving it if you can make a convincing enough case for it :)
I was hoping the binary can be moved to libexec, which means a man page is not strictly required. But apparently this can not be done due to the way how it is implemented. Olaf
On Mon, Jan 10, 2022 at 02:32:48PM +0100, Olaf Hering wrote:
Mon, 10 Jan 2022 13:29:28 +0000 Andrea Bolognani <abologna@redhat.com>:
I'm definitely open to moving it if you can make a convincing enough case for it :)
I was hoping the binary can be moved to libexec, which means a man page is not strictly required. But apparently this can not be done due to the way how it is implemented.
Right. We can still move the manual page to section 8 if we feel that it would be a bette match though. -- Andrea Bolognani / Red Hat / Virtualization
On Mon, Jan 10, 2022 at 01:29:54PM +0100, Olaf Hering wrote:
Mon, 13 Dec 2021 14:44:51 +0100 Andrea Bolognani <abologna@redhat.com>:
+``virt-ssh-helper`` is an internal tool
If it is indeed an internal tool, why is the man page in section 1, and why is it in PATH?
We explicitly want virt-ssh-helper in $PATH, because this is designed to remove the assumption that the libvirt client is compiled with the same $prefix setting as the libvirt host. Hardcoding libexec would be a step backwards. Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
On Mon, Dec 13, 2021 at 02:44:50PM +0100, Andrea Bolognani wrote:
Changes from [v1]:
* the commit message has been updated to include the rationale for adding a manual page for virt-ssh-helper.
[v1] https://listman.redhat.com/archives/libvir-list/2021-December/msg00466.html
Andrea Bolognani (1): virt-ssh-helper: Add manual page
ping -- Andrea Bolognani / Red Hat / Virtualization
participants (4)
-
Andrea Bolognani -
Daniel P. Berrangé -
Michal Prívozník -
Olaf Hering