From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by lists.proxmox.com (Postfix) with ESMTPS id 4B9D46AFD6 for ; Mon, 25 Jan 2021 15:54:43 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 427F8CA70 for ; Mon, 25 Jan 2021 15:54:13 +0100 (CET) Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com [212.186.127.180]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS id 53578CA68 for ; Mon, 25 Jan 2021 15:54:12 +0100 (CET) Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1]) by proxmox-new.maurer-it.com (Proxmox) with ESMTP id 2201045751 for ; Mon, 25 Jan 2021 15:54:12 +0100 (CET) From: Aaron Lauterer To: pve-devel@lists.proxmox.com Date: Mon, 25 Jan 2021 15:54:09 +0100 Message-Id: <20210125145410.6434-1-a.lauterer@proxmox.com> X-Mailer: git-send-email 2.20.1 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-SPAM-LEVEL: Spam detection results: 0 AWL -0.021 Adjusted score from AWL reputation of From: address KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Subject: [pve-devel] [PATCH v3 docs] qm: add guest agent section X-BeenThere: pve-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox VE development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 25 Jan 2021 14:54:43 -0000 Signed-off-by: Aaron Lauterer --- changes v2->v3: incorporated suggestions from Oguz, Stoiko and Thomas Over christmas and NYE I forgot about this patch series that's why it took some time for v3 :/ qm.adoc | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/qm.adoc b/qm.adoc index 9c54903..0d9c10e 100644 --- a/qm.adoc +++ b/qm.adoc @@ -917,6 +917,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 ~~~~~~~~~~~~~~~~~~ -- 2.20.1