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) server-digest SHA256) (No client certificate requested) by lists.proxmox.com (Postfix) with ESMTPS id 6D05C61693 for <pve-devel@lists.proxmox.com>; Thu, 17 Dec 2020 13:13:40 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 6085825281 for <pve-devel@lists.proxmox.com>; Thu, 17 Dec 2020 13:13:40 +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 B570625271 for <pve-devel@lists.proxmox.com>; Thu, 17 Dec 2020 13:13:38 +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 56AEF45242 for <pve-devel@lists.proxmox.com>; Thu, 17 Dec 2020 13:13:38 +0100 (CET) From: Aaron Lauterer <a.lauterer@proxmox.com> To: pve-devel@lists.proxmox.com Date: Thu, 17 Dec 2020 13:13:35 +0100 Message-Id: <20201217121336.4274-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. [proxmox.com, fedorapeople.org] Subject: [pve-devel] [PATCH v2 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: Thu, 17 Dec 2020 12:13:40 -0000 Signed-off-by: Aaron Lauterer <a.lauterer@proxmox.com> --- v1 -> v2: implemented suggested changes from Dylan. Thx for that. 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. [0] https://lists.proxmox.com/pipermail/pve-devel/2020-December/046502.html qm.adoc | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/qm.adoc b/qm.adoc index 5e53e4a..2a2efc7 100644 --- a/qm.adoc +++ b/qm.adoc @@ -917,6 +917,59 @@ 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. 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, for +example 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 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, +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 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, 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