Skip to navigationSkip to main contentSkip to footerScaleway DocsAsk our AI
Ask our AI
Log inSign up

Understanding the QEMU Guest Agent in Scaleway Instances

Some features of the Instances product require Scaleway's infrastructure to query or exchange information with your Instance. To enable this communication, a software component must run on the guest operating system: the QEMU Guest Agent (QGA).

This page provides essential insights into this mechanism.

Note

This documentation page does not apply to Instances running the Microsoft Windows operating system.

What is the QGA?

The QEMU Guest Agent (QGA) is a daemon designed to run inside virtual machines, enabling communication between the guest operating system and the QEMU hypervisor. It supports tasks such as system configuration and resource monitoring.

The QGA source code is publicly available in the QEMU repository on GitLab.

Note

In addition to the QGA, another daemon is preinstalled on recently created Instances: scaleway-vmagent. This agent was developed by Scaleway's engineering teams and is used to send metrics about your VM to Cockpit to monitor the status of your Instance. You can find the source code of the agent on Scaleway's Launchpad repository.

Which tasks are allowed for the QGA?

Scaleway has intentionally restricted the QGA to the following allowed tasks (configured in /etc/qemu/qemu-ga.conf):

  • guest-file-close
  • guest-file-open
  • guest-file-write
  • guest-ping

All other Remote Procedure Calls (RPCs) are disabled to limit the scope of external execution from the QEMU hypervisor.

What are the features provided by QGA?

Running the QEMU Guest Agent (QGA) on your Instance currently enables the following feature:

Additional features may be added in the future.

What is the performance impact of running the QGA inside my VM?

The performance impact of running the QGA is negligible. The agent consumes very little RAM (< 5 MB) and CPU (< 0.1%), and there is no measurable I/O or network overhead when idle. The only operation the agent performs is reading from or writing to a file in the VM each time a public IP is attached to or detached from the VM.

Checking QGA's status

Since March 1st, 2024, all Scaleway-provided GNU/Linux and InstantApp images for Instances come with QGA pre-installed and enabled by default.

To verify that QGA is running on your Instance, use the following command:

# systemctl is-active qemu-guest-agent.service

If the output is active, QGA is running, and you are ready to benefit from the associated features. If the output is inactive, you may need to install and/or activate QGA.

Opting in

Follow these steps to enable QGA on an Instance where it is currently inactive.

Installation

Instances created from images older than March 1st, 2024 may require manual installation of the qemu-guest-agent package:

  • Fedora / AlmaLinux / RockyLinux / CentOS

    # yum -y --best install qemu-guest-agent

  • Debian / Ubuntu

    # apt-get update
# apt-get -y install qemu-guest-agent

Activation

After installing the package, start the qemu-guest-agent.service by either:

  • Rebooting your Instance, or

  • Running the following command:

    # systemctl start qemu-guest-agent.service

Opting Out

Follow these steps to disable QGA and the associated Scaleway features.

Deactivation

Important

Disabling QGA is not recommended, as doing so also disables all the Scaleway features it provides.

To stop and disable QGA, run:

# systemctl stop qemu-guest-agent.service
# systemctl mask qemu-guest-agent.service

This stops the service and prevents it from starting on subsequent reboots.

Deinstallation (Optional)

Note

You do not necessarily need to deinstall QGA to opt out. Deactivating the service is sufficient.

If you prefer to completely remove QGA, ensure the service is stopped first, then run:

  • Fedora / AlmaLinux / RockyLinux / CentOS

    # yum -y remove qemu-guest-agent

  • Debian / Ubuntu

    # apt-get -y purge qemu-guest-agent
Still need help?

Create a support ticket
No Results