LIBVIRT-GUESTS(8)

💅 LIBVIRT-GUESTS(8) — the virtualization-support girlies' manual

okay so bestie, welcome to libvirt-guests from the Virtualization Support corner of the man-page universe. this is section 8, we're in the sysadmin trenches, and honestly? this page ate. let's go 🎀

---

✨ NAME ✨

libvirt-guests — suspend/resume running libvirt guests. that's the whole job. she suspends, she resumes, she does NOT do small talk 💅

---

🦋 SYNOPSIS 🦋

libvirt-guests COMMAND

one command. that's it. pick your COMMAND and go, no cap.

---

💖 DESCRIPTION 💖

so libvirt-guests is a service that can be used to coordinate guest and host lifecycle actions, iykyk. 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. literally the main character of host shutdowns 🌸

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. so systemd is basically her manager and honestly she's thriving under that representation ✨

but listen — libvirt-guests can also 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. yes that's a lot. yes she's versatile. periods. 👑

---

🧚 FILES 🧚

libvirt-guests defines several variables to control service behavior. the default value of these variables can be overridden in:

• /etc/sysconfig/libvirt-guests

the following variables are supported — buckle up bestie, there's a bunch 🍓

• URIS=default

URIs to check for running guests. example, copy it exactly: URIS='default xen:///system xen+tcp://host/system lxc:///system'

• ON_BOOT=start

action taken on host boot. two vibes to choose from:

• 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. so like… she's not doing it but somebody else is, whatever 🙈

• START_DELAY=0

number of seconds to wait between each guest start. set to 0 to allow parallel startup — that's the "everybody at once, chaos mode, we love her" option 🔥

• 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. not her being unable to tell "stuck" from "slow" 😭

• 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. it's giving controlled chaos 💜

• 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. trade-offs, bestie, it's always trade-offs 🎀

• 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. no agent, no sync, that's the deal 🙈

• PERSISTENT_ONLY=default

defines what type of guest virtual machine ON_SHUTDOWN action is applied to. three options, all iconic:

• default

this implements the already existing default behavior. if ON_SHUTDOWN action is shutdown, transient and persistent guest virtual machines are asked to shutdown. if ON_SHUTDOWN action is suspend, only persistent guest virtual machines are asked to suspend. she contains multitudes 💫

• true

ON_SHUTDOWN action is executed only on persistent guest virtual machines. transient guest virtual machines are not affected. not invited to the shutdown party 🚫

• false

ON_SHUTDOWN action is executed on persistent and transient guest virtual machines. everybody's invited, we're doing this 🌈

---

💀 BUGS 💀

please report all bugs you discover. this should be done via either:

1. the mailing list

https://libvirt.org/contact.html

2. the bug tracker

https://libvirt.org/bugs.html

alternatively, you may report bugs to your software distributor / vendor. find a bug, tell a friend, keep the ecosystem healthy 🫶

---

👑 AUTHORS 👑

please refer to the AUTHORS file distributed with libvirt. the credits are literally right there, go give them their flowers 🌸

---

⭐ 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. read that again — NO warranty, bestie, she said what she said 💅

---

🌟 SEE ALSO 🌟

libvirtd(8), https://libvirt.org/

---

and that's the page, mwah 💋 — signed off from the Virtualization Support section, this is LIBVIRT-GUESTS(8), catch you on the next reboot 🦋✨