[pve-devel] [PATCH v2 docs] qm: add guest agent section

[Aaron Lauterer <a.lauterer@proxmox.com>]

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