update link qemu documentation non web.archive

[pve-docs.git] / qm.adoc

diff --git a/qm.adoc b/qm.adoc
index 5e53e4a19d0ac87513be0e6ea2ad3b58d46e61fb..b84de9ea9f8751ed69afd57aa7e9958dde167da9 100644 (file)
--- a/qm.adoc
+++ b/qm.adoc
@@ -203,7 +203,7 @@ either the *raw disk image format* or the *QEMU image format*.
  format does not support thin provisioning or snapshots by itself, requiring
  cooperation from the storage layer for these tasks. It may, however, be up to
  10% faster than the *QEMU image format*. footnote:[See this benchmark for details
- http://events.linuxfoundation.org/sites/events/files/slides/CloudOpen2013_Khoa_Huynh_v3.pdf]
+ https://events.static.linuxfound.org/sites/events/files/slides/CloudOpen2013_Khoa_Huynh_v3.pdf]
  * the *VMware image format* only makes sense if you intend to import/export the
  disk image to other hypervisors.
 
@@ -776,9 +776,8 @@ shutdown or stopped. Open connections will still persist, but new connections
 to the exact same device cannot be made anymore.
 
 A use case for such a device is the Looking Glass
-footnote:[Looking Glass: https://looking-glass.hostfission.com/] project,
-which enables high performance, low-latency display mirroring between
-host and guest.
+footnote:[Looking Glass: https://looking-glass.io/] project, which enables high
+performance, low-latency display mirroring between host and guest.
 
 [[qm_audio_device]]
 Audio Device
@@ -796,11 +795,18 @@ Supported audio devices are:
 * `intel-hda`: Intel HD Audio Controller, emulates ICH6
 * `AC97`: Audio Codec '97, useful for older operating systems like Windows XP
 
-NOTE: The audio device works only in combination with SPICE. Remote protocols
-like Microsoft's RDP have options to play sound. To use the physical audio
-device of the host use device passthrough (see
-xref:qm_pci_passthrough[PCI Passthrough] and
-xref:qm_usb_passthrough[USB Passthrough]).
+There are two backends available:
+
+* 'spice'
+* 'none'
+
+The 'spice' backend can be used in combination with xref:qm_display[SPICE] while
+the 'none' backend can be useful if an audio device is needed in the VM for some
+software to work. To use the physical audio device of the host use device
+passthrough (see xref:qm_pci_passthrough[PCI Passthrough] and
+xref:qm_usb_passthrough[USB Passthrough]). Remote protocols like Microsoft’s RDP
+have options to play sound.
+
 
 [[qm_virtio_rng]]
 VirtIO RNG
@@ -917,6 +923,63 @@ start after those where the parameter is set. Further, this parameter can only
 be enforced between virtual machines running on the same host, not
 cluster-wide.
 
+
+[[qm_qemu_agent]]
+Qemu Guest Agent
+~~~~~~~~~~~~~~~~
+
+The Qemu Guest Agent is a service which runs inside the VM, providing a
+communication channel between the host and the guest. It is used to exchange
+information and allows the host to issue commands to the guest.
+
+For example, the IP addresses in the VM summary panel are fetched via the guest
+agent.
+
+Or when starting a backup, the guest is told via the guest agent to sync
+outstanding writes via the 'fs-freeze' and 'fs-thaw' commands.
+
+For the guest agent to work properly the following steps must be taken:
+
+* install the agent in the guest and make sure it is running
+* enable the communication via the agent in {pve}
+
+Install Guest Agent
+^^^^^^^^^^^^^^^^^^^
+
+For most Linux distributions, the guest agent is available. The package is
+usually named `qemu-guest-agent`.
+
+For Windows, it can be installed from the
+https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio/virtio-win.iso[Fedora
+VirtIO driver ISO].
+
+Enable Guest Agent Communication
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Communication from {pve} with the guest agent can be enabled in the VM's
+*Options* panel. A fresh start of the VM is necessary for the changes to take
+effect.
+
+It is possible to enable the 'Run guest-trim' option. With this enabled,
+{pve} will issue a trim command to the guest after the following
+operations that have the potential to write out zeros to the storage:
+
+* moving a disk to another storage
+* live migrating a VM to another node with local storage
+
+On a thin provisioned storage, this can help to free up unused space.
+
+Troubleshooting
+^^^^^^^^^^^^^^^
+
+.VM does not shut down
+
+Make sure the guest agent is installed and running.
+
+Once the guest agent is enabled, {pve} will send power commands like
+'shutdown' via the guest agent. If the guest agent is not running, commands
+cannot get executed properly and the shutdown command will run into a timeout.
+
 [[qm_spice_enhancements]]
 SPICE Enhancements
 ~~~~~~~~~~~~~~~~~~
@@ -1326,6 +1389,14 @@ Same as above, but only wait for 40 seconds.
 
  qm shutdown 300 && qm wait 300 -timeout 40
 
+Destroying a VM always removes it from Access Control Lists and it always
+removes the firewall configuration of the VM. You have to activate
+'--purge', if you want to additionally remove the VM from replication jobs,
+backup jobs and HA resource configurations.
+
+ qm destroy 300 --purge
+
+
 
 [[qm_configuration]]
 Configuration