|
 |
954c63 |
From 8363046dd5f3e018aaea7b6d9b711fb3d1e417cc Mon Sep 17 00:00:00 2001
|
|
|
954c63 |
Message-Id: <8363046dd5f3e018aaea7b6d9b711fb3d1e417cc@dist-git>
|
|
|
954c63 |
From: Jim Fehlig <jfehlig@suse.com>
|
|
|
954c63 |
Date: Fri, 7 Jan 2022 14:35:10 -0700
|
|
|
954c63 |
Subject: [PATCH] docs: Add man page for libvirt-guests
|
|
|
954c63 |
|
|
|
954c63 |
Signed-off-by: Jim Fehlig <jfehlig@suse.com>
|
|
|
954c63 |
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
|
|
|
954c63 |
(cherry picked from commit 161727417a91bdddf8f3167cf70c3de2829be81c)
|
|
|
954c63 |
|
|
|
954c63 |
https://bugzilla.redhat.com/show_bug.cgi?id=2042529
|
|
|
954c63 |
---
|
|
|
954c63 |
docs/manpages/index.rst | 1 +
|
|
|
954c63 |
docs/manpages/libvirt-guests.rst | 151 +++++++++++++++++++++++++++++++
|
|
|
954c63 |
docs/manpages/meson.build | 1 +
|
|
|
954c63 |
libvirt.spec.in | 1 +
|
|
|
954c63 |
tools/libvirt-guests.service.in | 2 +-
|
|
|
954c63 |
5 files changed, 155 insertions(+), 1 deletion(-)
|
|
|
954c63 |
create mode 100644 docs/manpages/libvirt-guests.rst
|
|
|
954c63 |
|
|
|
954c63 |
diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst
|
|
|
954c63 |
index fb4a36d46a..8fd0d90041 100644
|
|
|
954c63 |
--- a/docs/manpages/index.rst
|
|
|
954c63 |
+++ b/docs/manpages/index.rst
|
|
|
954c63 |
@@ -41,6 +41,7 @@ Tools
|
|
|
954c63 |
* `virt-admin(1) <virt-admin.html>`__ - daemon administration interface
|
|
|
954c63 |
* `virsh(1) <virsh.html>`__ - management user interface
|
|
|
954c63 |
* `virt-qemu-run(1) <virt-qemu-run.html>`__ - run standalone QEMU instances
|
|
|
954c63 |
+* `libvirt-guests(8) <libvirt-guests.html>`__ - suspend/resume running libvirt guests
|
|
|
954c63 |
|
|
|
954c63 |
Key codes
|
|
|
954c63 |
=========
|
|
|
954c63 |
diff --git a/docs/manpages/libvirt-guests.rst b/docs/manpages/libvirt-guests.rst
|
|
|
954c63 |
new file mode 100644
|
|
|
954c63 |
index 0000000000..76045ed11a
|
|
|
954c63 |
--- /dev/null
|
|
|
954c63 |
+++ b/docs/manpages/libvirt-guests.rst
|
|
|
954c63 |
@@ -0,0 +1,151 @@
|
|
|
954c63 |
+==============
|
|
|
954c63 |
+libvirt-guests
|
|
|
954c63 |
+==============
|
|
|
954c63 |
+
|
|
|
954c63 |
+-------------------------------------
|
|
|
954c63 |
+suspend/resume running libvirt guests
|
|
|
954c63 |
+-------------------------------------
|
|
|
954c63 |
+
|
|
|
954c63 |
+:Manual section: 8
|
|
|
954c63 |
+:Manual group: Virtualization Support
|
|
|
954c63 |
+
|
|
|
954c63 |
+.. contents::
|
|
|
954c63 |
+
|
|
|
954c63 |
+SYNOPSIS
|
|
|
954c63 |
+========
|
|
|
954c63 |
+
|
|
|
954c63 |
+``libvirt-guests`` *COMMAND*
|
|
|
954c63 |
+
|
|
|
954c63 |
+
|
|
|
954c63 |
+DESCRIPTION
|
|
|
954c63 |
+===========
|
|
|
954c63 |
+
|
|
|
954c63 |
+``libvirt-guests`` is a service that can be used to coordinate guest and host
|
|
|
954c63 |
+lifecyle actions. By default, ``libvirt-guests`` will suspend running guests
|
|
|
954c63 |
+when the host shuts down, and restore them to their pre-shutdown state when
|
|
|
954c63 |
+the host reboots.
|
|
|
954c63 |
+
|
|
|
954c63 |
+``libvirt-guests`` is typically under control of systemd. When
|
|
|
954c63 |
+``libvirt-guests.service`` is enabled, systemd will call ``libvirt-guests``
|
|
|
954c63 |
+with the ``start`` *COMMAND* when the host boots. Conversely, systemd will call
|
|
|
954c63 |
+``libvirt-guests`` with the ``stop`` *COMMAND* when the host shuts down.
|
|
|
954c63 |
+
|
|
|
954c63 |
+``libvirt-guests`` can be used directly. In addition to the ``start`` and
|
|
|
954c63 |
+``stop`` *COMMAND*\s, it also supports ``status``, ``restart``, ``condrestart``,
|
|
|
954c63 |
+``try-restart``, ``reload``, ``force-reload``, ``gueststatus``, and
|
|
|
954c63 |
+``shutdown`` *COMMAND*\s.
|
|
|
954c63 |
+
|
|
|
954c63 |
+
|
|
|
954c63 |
+FILES
|
|
|
954c63 |
+=====
|
|
|
954c63 |
+
|
|
|
954c63 |
+``libvirt-guests`` defines several variables to control service behavior.
|
|
|
954c63 |
+The default vaule of these variables can be overridden in:
|
|
|
954c63 |
+
|
|
|
954c63 |
+* ``@SYSCONFDIR@/sysconfig/libvirt-guests``
|
|
|
954c63 |
+
|
|
|
954c63 |
+The following variables are supported:
|
|
|
954c63 |
+
|
|
|
954c63 |
+- URIS=default
|
|
|
954c63 |
+
|
|
|
954c63 |
+ URIs to check for running guests. Example:
|
|
|
954c63 |
+ ``URIS='default xen:///system xen+tcp://host/system lxc:///system'``
|
|
|
954c63 |
+
|
|
|
954c63 |
+- ON_BOOT=start
|
|
|
954c63 |
+
|
|
|
954c63 |
+ Action taken on host boot
|
|
|
954c63 |
+
|
|
|
954c63 |
+ * start
|
|
|
954c63 |
+
|
|
|
954c63 |
+ All guests which were running on shutdown are started on boot regardless
|
|
|
954c63 |
+ of their autostart settings
|
|
|
954c63 |
+
|
|
|
954c63 |
+ * ignore
|
|
|
954c63 |
+
|
|
|
954c63 |
+ ``libvirt-guests`` won't start any guest on boot, however, guests marked
|
|
|
954c63 |
+ as autostart will still be automatically started by libvirtd
|
|
|
954c63 |
+
|
|
|
954c63 |
+- START_DELAY=0
|
|
|
954c63 |
+
|
|
|
954c63 |
+ Number of seconds to wait between each guest start. Set to 0 to allow parallel
|
|
|
954c63 |
+ startup.
|
|
|
954c63 |
+
|
|
|
954c63 |
+- ON_SHUTDOWN=suspend
|
|
|
954c63 |
+
|
|
|
954c63 |
+ Action taken on host shutdown
|
|
|
954c63 |
+
|
|
|
954c63 |
+ * suspend
|
|
|
954c63 |
+
|
|
|
954c63 |
+ All running guests are suspended using virsh managedsave
|
|
|
954c63 |
+
|
|
|
954c63 |
+ * shutdown
|
|
|
954c63 |
+
|
|
|
954c63 |
+ All running guests are asked to shutdown. Please be careful with this
|
|
|
954c63 |
+ settings since there is no way to distinguish between a guest which is
|
|
|
954c63 |
+ stuck or ignores shutdown requests and a guest which just needs a long
|
|
|
954c63 |
+ time to shutdown. When setting ON_SHUTDOWN=shutdown, you must also set
|
|
|
954c63 |
+ SHUTDOWN_TIMEOUT to a value suitable for your guests.
|
|
|
954c63 |
+
|
|
|
954c63 |
+- PARALLEL_SHUTDOWN=0
|
|
|
954c63 |
+
|
|
|
954c63 |
+ Number of guests will be shutdown concurrently, taking effect when
|
|
|
954c63 |
+ "ON_SHUTDOWN" is set to "shutdown". If Set to 0, guests will be shutdown one
|
|
|
954c63 |
+ after another. Number of guests on shutdown at any time will not exceed number
|
|
|
954c63 |
+ set in this variable.
|
|
|
954c63 |
+
|
|
|
954c63 |
+- SHUTDOWN_TIMEOUT=300
|
|
|
954c63 |
+
|
|
|
954c63 |
+ Number of seconds we're willing to wait for a guest to shut down. If parallel
|
|
|
954c63 |
+ shutdown is enabled, this timeout applies as a timeout for shutting down all
|
|
|
954c63 |
+ guests on a single URI defined in the variable URIS. If this is 0, then there
|
|
|
954c63 |
+ is no time out (use with caution, as guests might not respond to a shutdown
|
|
|
954c63 |
+ request). The default value is 300 seconds (5 minutes).
|
|
|
954c63 |
+
|
|
|
954c63 |
+- BYPASS_CACHE=0
|
|
|
954c63 |
+
|
|
|
954c63 |
+ If non-zero, try to bypass the file system cache when saving and
|
|
|
954c63 |
+ restoring guests, even though this may give slower operation for
|
|
|
954c63 |
+ some file systems.
|
|
|
954c63 |
+
|
|
|
954c63 |
+- SYNC_TIME=0
|
|
|
954c63 |
+
|
|
|
954c63 |
+ If non-zero, try to sync guest time on domain resume. Be aware, that
|
|
|
954c63 |
+ this requires guest agent with support for time synchronization
|
|
|
954c63 |
+ running in the guest. By default, this functionality is turned off.
|
|
|
954c63 |
+
|
|
|
954c63 |
+
|
|
|
954c63 |
+BUGS
|
|
|
954c63 |
+====
|
|
|
954c63 |
+
|
|
|
954c63 |
+Please report all bugs you discover. This should be done via either:
|
|
|
954c63 |
+
|
|
|
954c63 |
+#. the mailing list
|
|
|
954c63 |
+
|
|
|
954c63 |
+ `https://libvirt.org/contact.html <https://libvirt.org/contact.html>`_
|
|
|
954c63 |
+
|
|
|
954c63 |
+#. the bug tracker
|
|
|
954c63 |
+
|
|
|
954c63 |
+ `https://libvirt.org/bugs.html <https://libvirt.org/bugs.html>`_
|
|
|
954c63 |
+
|
|
|
954c63 |
+Alternatively, you may report bugs to your software distributor / vendor.
|
|
|
954c63 |
+
|
|
|
954c63 |
+
|
|
|
954c63 |
+AUTHORS
|
|
|
954c63 |
+=======
|
|
|
954c63 |
+
|
|
|
954c63 |
+Please refer to the AUTHORS file distributed with libvirt.
|
|
|
954c63 |
+
|
|
|
954c63 |
+
|
|
|
954c63 |
+LICENSE
|
|
|
954c63 |
+=======
|
|
|
954c63 |
+
|
|
|
954c63 |
+``libvirt-guests`` is distributed under the terms of the GNU LGPL v2.1+.
|
|
|
954c63 |
+This is free software; see the source for copying conditions. There
|
|
|
954c63 |
+is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
|
|
|
954c63 |
+PURPOSE
|
|
|
954c63 |
+
|
|
|
954c63 |
+
|
|
|
954c63 |
+SEE ALSO
|
|
|
954c63 |
+========
|
|
|
954c63 |
+
|
|
|
954c63 |
+libvirtd(8), `https://libvirt.org/ <https://libvirt.org/>`_
|
|
|
954c63 |
diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build
|
|
|
954c63 |
index 150f45d296..bad9b62a2e 100644
|
|
|
954c63 |
--- a/docs/manpages/meson.build
|
|
|
954c63 |
+++ b/docs/manpages/meson.build
|
|
|
954c63 |
@@ -21,6 +21,7 @@ docs_man_files = [
|
|
|
954c63 |
{ 'name': 'virt-qemu-run', 'section': '1', 'install': conf.has('WITH_QEMU') },
|
|
|
954c63 |
{ 'name': 'virt-xml-validate', 'section': '1', 'install': true },
|
|
|
954c63 |
|
|
|
954c63 |
+ { 'name': 'libvirt-guests', 'section': '8', 'install': conf.has('WITH_LIBVIRTD') },
|
|
|
954c63 |
{ 'name': 'libvirtd', 'section': '8', 'install': conf.has('WITH_LIBVIRTD') },
|
|
|
954c63 |
{ 'name': 'virt-sanlock-cleanup', 'section': '8', 'install': conf.has('WITH_SANLOCK') },
|
|
|
954c63 |
{ 'name': 'virt-ssh-helper', 'section': '8', 'install': conf.has('WITH_LIBVIRTD') },
|
|
|
954c63 |
diff --git a/tools/libvirt-guests.service.in b/tools/libvirt-guests.service.in
|
|
|
954c63 |
index 10c664016a..1a9b233e11 100644
|
|
|
954c63 |
--- a/tools/libvirt-guests.service.in
|
|
|
954c63 |
+++ b/tools/libvirt-guests.service.in
|
|
|
954c63 |
@@ -6,7 +6,7 @@ After=network.target
|
|
|
954c63 |
After=time-sync.target
|
|
|
954c63 |
After=libvirtd.service
|
|
|
954c63 |
After=virt-guest-shutdown.target
|
|
|
954c63 |
-Documentation=man:libvirtd(8)
|
|
|
954c63 |
+Documentation=man:libvirt-guests(8)
|
|
|
954c63 |
Documentation=https://libvirt.org
|
|
|
954c63 |
|
|
|
954c63 |
[Service]
|
|
|
954c63 |
--
|
|
|
954c63 |
2.35.0
|
|
|
954c63 |
|