From 8363046dd5f3e018aaea7b6d9b711fb3d1e417cc Mon Sep 17 00:00:00 2001

Message-Id: <8363046dd5f3e018aaea7b6d9b711fb3d1e417cc@dist-git>

From: Jim Fehlig <jfehlig@suse.com>

Date: Fri, 7 Jan 2022 14:35:10 -0700

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

Signed-off-by: Jim Fehlig <jfehlig@suse.com>

Reviewed-by: Andrea Bolognani <abologna@redhat.com>

(cherry picked from commit 161727417a91bdddf8f3167cf70c3de2829be81c)

https://bugzilla.redhat.com/show_bug.cgi?id=2042529

---

 docs/manpages/index.rst          |   1 +

 docs/manpages/libvirt-guests.rst | 151 +++++++++++++++++++++++++++++++

 docs/manpages/meson.build        |   1 +

 libvirt.spec.in                  |   1 +

 tools/libvirt-guests.service.in  |   2 +-

 5 files changed, 155 insertions(+), 1 deletion(-)

 create mode 100644 docs/manpages/libvirt-guests.rst

diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst

index fb4a36d46a..8fd0d90041 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..76045ed11a

--- /dev/null

+++ b/docs/manpages/libvirt-guests.rst

@@ -0,0 +1,151 @@

+==============

+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`` *COMMAND*\s, it also supports ``status``, ``restart``, ``condrestart``,

+``try-restart``, ``reload``, ``force-reload``, ``gueststatus``, and

+``shutdown`` *COMMAND*\s.

+

+

+FILES

+=====

+

+``libvirt-guests`` defines several variables to control service behavior.

+The default vaule of these variables can be overridden in:

+

+* ``@SYSCONFDIR@/sysconfig/libvirt-guests``

+

+The following variables are supported:

+

+- URIS=default

+

+  URIs to check for running guests. Example:

+  ``URIS='default xen:///system xen+tcp://host/system lxc:///system'``

+

+- 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=0

+

+  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 150f45d296..bad9b62a2e 100644

--- a/docs/manpages/meson.build

+++ b/docs/manpages/meson.build

@@ -21,6 +21,7 @@ docs_man_files = [

   { 'name': 'virt-qemu-run', 'section': '1', 'install': conf.has('WITH_QEMU') },

   { 'name': 'virt-xml-validate', 'section': '1', 'install': true },

+  { 'name': 'libvirt-guests', 'section': '8', 'install': conf.has('WITH_LIBVIRTD') },

   { 'name': 'libvirtd', 'section': '8', 'install': conf.has('WITH_LIBVIRTD') },

   { 'name': 'virt-sanlock-cleanup', 'section': '8', 'install': conf.has('WITH_SANLOCK') },

   { 'name': 'virt-ssh-helper', 'section': '8', 'install': conf.has('WITH_LIBVIRTD') },

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.35.0