[PATCH] docs: Add man page for libvirt-guests

Andrea Bolognani abologna at redhat.com
Mon Jan 10 14:30:13 UTC 2022


On Fri, Jan 07, 2022 at 02:38:15PM -0700, Jim Fehlig wrote:
> +++ b/docs/manpages/index.rst
> @@ -41,6 +41,7 @@ Tools
>  * `virt-admin(1) <virt-admin.html>`__ - daemon administration interface
>  * `virsh(1) <virsh.html>`__ - management user interface
>  * `virt-qemu-run(1) <virt-qemu-run.html>`__ - run standalone QEMU instances
> +* `libvirt-guests(8) <libvirt-guests.html>`__ - Suspend/Resume running libvirt guests

This should be "suspend/resume" to match the existing entries.

> +++ b/docs/manpages/libvirt-guests.rst
> @@ -0,0 +1,146 @@
> +``libvirt-guests`` is typically under control of systemd. When
> +``libvirt-guests.service`` is enabled, systemd will call ``libvirt-guests``
> +with the ``start`` *command* when the host boots. Conversely, systemd will call
> +``libvirt-guests`` with the ``stop`` *command* when the host shuts down.
>
> +``libvirt-guests`` can be used directly. In addition to the ``start`` and
> +``stop`` *commands*, it also supports ``status``, ``restart``, ``condrestart``,
> +``try-restart``, ``reload``, ``force-reload``, ``gueststatus``, and
> +``shutdown`` *commands*.

If you're using "*command*" to refer to the corresponding command
line argument, I think the convention would be to keep it upper case
even when it's used as part of a sentence and use "*COMMAND*\s" for
plurals.

> +ENVIRONMENT
> +===========
> +
> +The following environment variables can be used to alter the behavior of
> +``libvirt-guests``

As Olaf already pointed out, these environment variables have to be
specified in the sysconfig file. This is something that should be
documented explicitly.

> +- URIS=default
> +
> +  URIs to check for running guests

The sysconfig file contains an example, which I think would be useful
to have here as well.

> +- BYPASS_CACHE=0
> +
> +   If non-zero, try to bypass the file system cache when saving and
> +   restoring guests, even though this may give slower operation for
> +   some file systems.

Indentation is slightly off here.

> + - SYNC_TIME=1
> +
> +   If non-zero, try to sync guest time on domain resume. Be aware, that
> +   this requires guest agent with support for time synchronization
> +   running in the guest. By default, this functionality is turned off.

Indentation is also slightly off here, and the item is interpreted to
be part of a nested list as a consequence.

SYNC_TIME should be set to 0 rather than 1 above, to accurately
reflect the default value.

> +++ b/docs/manpages/meson.build
> @@ -39,6 +39,7 @@ docs_man_files = [
>    { 'name': 'virtvboxd', 'section': '8', 'install': conf.has('WITH_VBOX') },
>    { 'name': 'virtvzd', 'section': '8', 'install': conf.has('WITH_VZ') },
>    { 'name': 'virtxend', 'section': '8', 'install': conf.has('WITH_LIBXL') },
> +  { 'name': 'libvirt-guests', 'section': '8', 'install': true },

I would have expected

  'install': conf.has('WITH_LIBVIRTD')

here but I see that we actually install the script and its unit file
unconditionally. I think that might be a bug, but it also looks like
the script supports starting/stopping *remote* guests when the host
power cycles? That'd be an interesting setup :)

You should make sure to tweak libvirt.spec.in so that the manual page
gets included in RPM packages.

-- 
Andrea Bolognani / Red Hat / Virtualization




More information about the libvir-list mailing list