====== Guest Agent ======

Proxmox vm's use the QEMU guest agent. The official documentation from Proxmox can be found here: [[https://pve.proxmox.com/wiki/Qemu-guest-agent]]

===== Proxmox VE VM Config =====

  * Open the Proxmox VE UI
  * Open the vm
  * Options
  * QEMU Guest Agent
  * Check: Use QEMU Guest Agent
  * Power off the vm and start it again

If this option is set, a new virtual serial device is shown to the vm, which will be accessed by the agent which will be installed in the guest os.

To set this option via cli use the following command:
<code>
qm set VMID --agent 1
</code>


===== Execute Command =====

==== Enable ====

Per default the qemu-guest-agent doesn't allow command execution. You will see the following error message, if you try it: 

<code>
root@mypve:~# qm guest exec 101 /bin/ls
Agent error: The command guest-exec has been disabled for this instance
</code>

=== CentOS / RHEL ===

Open the config file.
<code>
vi /etc/sysconfig/qemu-ga
</code>

Search for the blacklist line.
<code>
BLACKLIST_RPC=guest-file-open,guest-file-close,guest-file-read,guest-file-write,guest-file-seek,guest-file-flush,guest-exec,guest-exec-status
</code>

Remove guest-exec (and guest-exec-status for async exec calls).
<code>
BLACKLIST_RPC=guest-file-open,guest-file-close,guest-file-read,guest-file-write,guest-file-seek,guest-file-flush
</code>

Restart the agent.
<code>
systemctl restart qemu-guest-agent
</code>

==== Use ====

<code>
qm guest exec <vmid> <command> <arg1> <arg2> ...
</code>

<code>
root@mypve:~# qm guest exec 101 /bin/ls -- "-la" "/etc/hosts"
{
   "exitcode" : 0,
   "exited" : 1,
   "out-data" : "-rw-r--r--. 1 root root 158 Sep 10  2018 /etc/hosts\n"
}
</code>

===== Installation on Windows =====

  * Download the latest VirtIO ISO ([[https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/archive-virtio/|Fedora VirtIO Archive]])
  * Mount the ISO to the vm
  * Open the device manager
  * Search the device "PCI Simple Communications Controller"
  * Install the driver for this device from the mounted ISO
  * Start the Guest Agent installer from the mounted ISO ("X:\guest-agent\qemu-ga-x86_64.msi")
  * Reboot the vm

===== Installation on Linux =====

For Debian/Ubuntu based systems:
<code>
apt install qemu-guest-agent
</code>

For RedHat based systems:
<code>
yum install qemu-guest-agent
</code>

Start the service:
<code>
systemctl start qemu-guest-agent
</code>

===== Troubleshooting =====

=== Timed out waiting for device ===

Starting the systemd unit file takes a long time and fails. You see the following errors in the journal:
<code>
Apr 10 18:14:39 pmg systemd[1]: dev-virtio\x2dports-org.qemu.guest_agent.0.device: Job dev-virtio\x2dports-org.qemu.guest_agent.0.device/start ti
Apr 10 18:14:39 pmg systemd[1]: Timed out waiting for device /dev/virtio-ports/org.qemu.guest_agent.0.
</code>

You probably forgot to enable the QEMU Guest Agent setting in the vm settings.

=== Agent on Windows is started but doesn't work ===

If the QEMU Guest Agent service is startet but in the vm overview you see "QEMU Guest Agent not running" then you probably forgot to enable the QEMU Guest Agent setting in the vm settings.