From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: <s.ivanov@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 CC0DB61650 for <pve-devel@lists.proxmox.com>; Thu, 17 Dec 2020 14:23:40 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id B95B42696C for <pve-devel@lists.proxmox.com>; Thu, 17 Dec 2020 14:23:10 +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) server-digest SHA256) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS id E47B926940 for <pve-devel@lists.proxmox.com>; Thu, 17 Dec 2020 14:23:08 +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 B3C3244110 for <pve-devel@lists.proxmox.com>; Thu, 17 Dec 2020 14:23:08 +0100 (CET) Date: Thu, 17 Dec 2020 14:23:07 +0100 From: Stoiko Ivanov <s.ivanov@proxmox.com> To: Aaron Lauterer <a.lauterer@proxmox.com> Cc: Proxmox VE development discussion <pve-devel@lists.proxmox.com> Message-ID: <20201217142307.2bdfdb9e@rosa.proxmox.com> In-Reply-To: <20201217121336.4274-1-a.lauterer@proxmox.com> References: <20201217121336.4274-1-a.lauterer@proxmox.com> X-Mailer: Claws Mail 3.17.3 (GTK+ 2.24.32; x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit X-SPAM-LEVEL: Spam detection results: 0 AWL 0.074 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: Re: [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 13:23:40 -0000 Thanks for getting this documented! LGTM as it currently is! (All comments are purely suggestions - feel free to ignore them) One thing I would emphasize a bit more (e.g. by adding it as list items in the initial paragraph) is that getting all the guest agent goodness needs 2 prerequisites: * installing the agent in the guest * enabling the communication from the hypervisor (by enabling it in the guest's config) Some (minor) comments inline: On Thu, 17 Dec 2020 13:13:35 +0100 Aaron Lauterer <a.lauterer@proxmox.com> wrote: > 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 I personally would probably separate the displaying IP-information and the fs-freeze/thaw part into 2 paragraphs. > +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 When I read hook scripts in our documentation I always think first of the various places where we allow to add custom (hook) scripts. Not 100% sure we need to document qga-features here? > +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. maybe: s/The guest agent can be/Communcation from PVE with the guest agent can be/ > + > +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. Maybe: If the guest agent is not running/listening for commands - they cannot get executed properly and the shutdown command will run into a timeout. > + > + > [[qm_spice_enhancements]] > SPICE Enhancements > ~~~~~~~~~~~~~~~~~~