From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: <a.lauterer@proxmox.com> 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 CF9E161252 for <pve-devel@lists.proxmox.com>; Wed, 16 Dec 2020 15:39:06 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id C743C1DB76 for <pve-devel@lists.proxmox.com>; Wed, 16 Dec 2020 15:38:36 +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 ECC4F1DB6E for <pve-devel@lists.proxmox.com>; Wed, 16 Dec 2020 15:38:35 +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 B97814521C for <pve-devel@lists.proxmox.com>; Wed, 16 Dec 2020 15:38:35 +0100 (CET) From: Aaron Lauterer <a.lauterer@proxmox.com> To: pve-devel@lists.proxmox.com Date: Wed, 16 Dec 2020 15:38:33 +0100 Message-Id: <20201216143834.21446-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.004 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 URIBL_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to URIBL was blocked. See http://wiki.apache.org/spamassassin/DnsBlocklists#dnsbl-block for more information. [fedorapeople.org, proxmox.com] Subject: [pve-devel] [PATCH 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 <pve-devel.lists.proxmox.com> List-Unsubscribe: <https://lists.proxmox.com/cgi-bin/mailman/options/pve-devel>, <mailto:pve-devel-request@lists.proxmox.com?subject=unsubscribe> List-Archive: <http://lists.proxmox.com/pipermail/pve-devel/> List-Post: <mailto:pve-devel@lists.proxmox.com> List-Help: <mailto:pve-devel-request@lists.proxmox.com?subject=help> List-Subscribe: <https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel>, <mailto:pve-devel-request@lists.proxmox.com?subject=subscribe> X-List-Received-Date: Wed, 16 Dec 2020 14:39:06 -0000 Signed-off-by: Aaron Lauterer <a.lauterer@proxmox.com> --- Additionally to the previous series [0] which changes the phrasing, it would be nice to have a dedicated Qemu Guest Agent section in the docs. This is a first draft. If there is something missing or could be phrased / structured in a better way, let me know :) [0] https://lists.proxmox.com/pipermail/pve-devel/2020-December/046502.html qm.adoc | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/qm.adoc b/qm.adoc index 5e53e4a..9c121f1 100644 --- a/qm.adoc +++ b/qm.adoc @@ -917,6 +917,58 @@ 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 is running 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. When starting a backup, the guest is told via the guest agent to sync +outstanding writes via the 'fs-freeze' and 'fs-thaw' commands. It is possible +to add custom hook scripts to react to these commands and tell software like a +database server to write current data to disk so it is included in the backup. + +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 +^^^^^^^^^^^^^^^^^^ + +The guest agent can be enabled in the VMs *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'. With this option enabled, +Proxmox VE 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 storages 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, Proxmox VE will send power commands like +'shutdown' via the guest agent. These commands will be ignored if the guest +agent in the VM is not running. + + [[qm_spice_enhancements]] SPICE Enhancements ~~~~~~~~~~~~~~~~~~ -- 2.20.1