> ## Documentation Index
> Fetch the complete documentation index at: https://help.onetsolutions.net/llms.txt
> Use this file to discover all available pages before exploring further.

# QEMU Guest Agent

> Install and configure the QEMU Guest Agent on your VPS for improved performance and management

The QEMU Guest Agent is an essential component for communication between the host and QEMU-based virtual machines. It enables features like proper shutdown, filesystem freeze for snapshots, and improved VM management.

<Info>
  **Prerequisites**

  * A VPS with OnetSolutions
  * SSH or console access to your server
  * Root or sudo privileges
</Info>

## Installation Instructions

<Tabs>
  <Tab title="Debian/Ubuntu">
    <Steps>
      <Step title="Update package lists">
        ```bash theme={null}
        sudo apt update
        ```
      </Step>

      <Step title="Install the QEMU Guest Agent">
        ```bash theme={null}
        sudo apt install qemu-guest-agent
        ```
      </Step>

      <Step title="Start the service">
        ```bash theme={null}
        sudo systemctl start qemu-guest-agent
        ```
      </Step>

      <Step title="Enable automatic startup">
        ```bash theme={null}
        sudo systemctl enable qemu-guest-agent
        ```
      </Step>

      <Step title="Verify the installation">
        ```bash theme={null}
        sudo systemctl status qemu-guest-agent
        ```

        You should see a message indicating the service is active and running.
      </Step>
    </Steps>
  </Tab>

  <Tab title="CentOS/Rocky/Alma">
    <Steps>
      <Step title="Install the QEMU Guest Agent">
        ```bash theme={null}
        sudo yum install qemu-guest-agent
        ```

        Or on newer systems with dnf:

        ```bash theme={null}
        sudo dnf install qemu-guest-agent
        ```
      </Step>

      <Step title="Start the service">
        ```bash theme={null}
        sudo systemctl start qemu-guest-agent
        ```
      </Step>

      <Step title="Enable automatic startup">
        ```bash theme={null}
        sudo systemctl enable qemu-guest-agent
        ```
      </Step>

      <Step title="Verify the installation">
        ```bash theme={null}
        sudo systemctl status qemu-guest-agent
        ```

        You should see a message indicating the service is active and running.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Windows Server">
    <Steps>
      <Step title="Download the installer">
        Download the QEMU Guest Agent installer from [virtio-win releases](https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/archive-qemu-ga/qemu-ga-win-105.0.2-1.el9/qemu-ga-x86_64.msi).
      </Step>

      <Step title="Run the installer">
        Execute the downloaded `qemu-ga-x86_64.msi` file and follow the on-screen instructions. Accept the license agreement when prompted.
      </Step>

      <Step title="Verify the installation">
        Open Task Manager and look for the `qemu-ga.exe` process. If it's running, the agent is installed correctly.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Configuration (Optional)

On Linux systems, you can customize the QEMU Guest Agent behavior by editing its configuration file:

```bash theme={null}
sudo nano /etc/qemu/qemu-guest-agent.conf
```

<Note>
  The default configuration works well for most use cases. Only modify this file if you have specific requirements.
</Note>

## Troubleshooting

<Accordion title="Service fails to start">
  Ensure the QEMU Guest Agent channel is enabled on your VM. Contact OnetSolutions support if the issue persists.
</Accordion>

<Accordion title="Agent not communicating with host">
  Restart the service and check the logs:

  ```bash theme={null}
  sudo systemctl restart qemu-guest-agent
  sudo journalctl -u qemu-guest-agent
  ```
</Accordion>