Signed-off-by: Jim Fehlig <jfehlig@suse.com>
---
 docs/manpages/index.rst          |   1 +
 docs/manpages/libvirt-guests.rst | 146 +++++++++++++++++++++++++++++++
 docs/manpages/meson.build        |   1 +
 tools/libvirt-guests.service.in  |   2 +-
 4 files changed, 149 insertions(+), 1 deletion(-)

diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst
index fb4a36d46a..b2717bc9f2 100644
--- a/docs/manpages/index.rst
+++ 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
 
 Key codes
 =========
diff --git a/docs/manpages/libvirt-guests.rst b/docs/manpages/libvirt-guests.rst
new file mode 100644
index 0000000000..9dc7ed3473
--- /dev/null
+++ b/docs/manpages/libvirt-guests.rst
@@ -0,0 +1,146 @@
+==============
+libvirt-guests
+==============
+
+-------------------------------------
+suspend/resume running libvirt guests
+-------------------------------------
+
+:Manual section: 8
+:Manual group: Virtualization Support
+
+.. contents::
+
+SYNOPSIS
+========
+
+``libvirt-guests`` *COMMAND*
+
+
+DESCRIPTION
+===========
+
+``libvirt-guests`` is a service that can be used to coordinate guest and host
+lifecyle actions. By default, ``libvirt-guests`` will suspend running guests
+when the host shuts down, and restore them to their pre-shutdown state when
+the host reboots.
+
+``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*.
+
+
+ENVIRONMENT
+===========
+
+The following environment variables can be used to alter the behavior of
+``libvirt-guests``
+
+- URIS=default
+
+  URIs to check for running guests
+
+- ON_BOOT=start
+
+  Action taken on host boot
+
+  * start
+
+    All guests which were running on shutdown are started on boot regardless
+    of their autostart settings
+
+  * ignore
+
+    ``libvirt-guests`` won't start any guest on boot, however, guests marked
+    as autostart will still be automatically started by libvirtd
+
+- START_DELAY=0
+
+  Number of seconds to wait between each guest start. Set to 0 to allow parallel
+  startup.
+
+- ON_SHUTDOWN=suspend
+
+  Action taken on host shutdown
+
+  * suspend
+
+    All running guests are suspended using virsh managedsave
+
+  * shutdown
+
+    All running guests are asked to shutdown. Please be careful with this
+    settings since there is no way to distinguish between a guest which is
+    stuck or ignores shutdown requests and a guest which just needs a long
+    time to shutdown. When setting ON_SHUTDOWN=shutdown, you must also set
+    SHUTDOWN_TIMEOUT to a value suitable for your guests.
+
+- PARALLEL_SHUTDOWN=0
+
+  Number of guests will be shutdown concurrently, taking effect when
+  "ON_SHUTDOWN" is set to "shutdown". If Set to 0, guests will be shutdown one
+  after another. Number of guests on shutdown at any time will not exceed number
+  set in this variable.
+
+- SHUTDOWN_TIMEOUT=300
+
+  Number of seconds we're willing to wait for a guest to shut down. If parallel
+  shutdown is enabled, this timeout applies as a timeout for shutting down all
+  guests on a single URI defined in the variable URIS. If this is 0, then there
+  is no time out (use with caution, as guests might not respond to a shutdown
+  request). The default value is 300 seconds (5 minutes).
+
+- 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.
+
+ - 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.
+
+
+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.
+
+
+AUTHORS
+=======
+
+Please refer to the AUTHORS file distributed with libvirt.
+
+
+LICENSE
+=======
+
+``libvirt-guests`` is distributed under the terms of the GNU LGPL v2.1+.
+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
+========
+
+libvirtd(8), `https://libvirt.org/ <https://libvirt.org/>`_
diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build
index 6763d19af8..2c84011aa7 100644
--- a/docs/manpages/meson.build
+++ 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 },
 ]
 
 foreach name : keycode_list
diff --git a/tools/libvirt-guests.service.in b/tools/libvirt-guests.service.in
index 10c664016a..1a9b233e11 100644
--- a/tools/libvirt-guests.service.in
+++ b/tools/libvirt-guests.service.in
@@ -6,7 +6,7 @@ After=network.target
 After=time-sync.target
 After=libvirtd.service
 After=virt-guest-shutdown.target
-Documentation=man:libvirtd(8)
+Documentation=man:libvirt-guests(8)
 Documentation=https://libvirt.org
 
 [Service]
-- 
2.34.1

Fri,  7 Jan 2022 14:38:15 -0700 Jim Fehlig <jfehlig@suse.com>:

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

I think the script does not take environment variables at this point.

In its current form the only way to configure it is a sysconfig file which redefines the variables.
This fact should be mentioned.

Olaf

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

On 1/10/22 07:30, Andrea Bolognani wrote:
> On Fri, Jan 07, 2022 at 02:38:15PM -0700, Jim Fehlig wrote:
>> +++ 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')

Agreed, but I was lazy and went with the status quo.
> 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 :)

IMO it is a bug. I was less lazy in V2 and included a patch the only installs 
libvirt-guests when also building libvirtd

https://listman.redhat.com/archives/libvir-list/2022-January/msg00399.html

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

Nod. I also verified CI passed against V2 :-)

https://gitlab.com/jfehlig/libvirt/-/pipelines/445122167

Regards,
Jim