QEMU

The following page documents the QEMU cloud integration in pycloudlib.

Support

Pycloudlib currently supports launching x86-64 Ubuntu images using qemu-system-x86_64 on an x86-64 host.

Requirements

In addition to requirements specified in setup.py, on Ubuntu systems, the QEMU cloud requires the following packages:

  • qemu-system-x86

  • qemu-utils # for qemu-img

  • genisoimage # to create the cloud-init NoCloud seed image

Configuration and Local Storage

QEMU instances require local directories to store images and instances. These directories can be configured in the pycloudlib.toml file:

image_dir - Directory to look for images when launching instances. Also the directory to download images to where supported.

working_dir - Directory to store temporary instance data. This includes instance disks, snapshots, and other metadata.

qemu_binary - Path to the qemu-system-x86_64 binary.

Obtaining Images

While any x64-64 should be usable, Ubuntu images can be downloaded from the Ubuntu cloud images website using the cloud daily_image and released_image calls.

For example:

cloud = Qemu(...)
cloud.released_image("jammy")

will return the path to the latest jammy image that has already been downloaded by Pycloudlib. If no image exists, it will be downloaded into the image_dir.

cloud = Qemu(...)
cloud.daily_image("jammy")

will return the path to the latest jammy image that has been released. If the image does not exist, it will be downloaded into the image_dir.

Launching Instances

Launching instances with QEMU requires an image_id.

The image_id can either be an absolute path image, or a path relative to the image_dir. It is most easily retrieved using the daily_image or released_image calls.

The instance_type is in the form of c<cpus>m<memory>, where <cpus> is the number of CPUs to allocate to the instance and <memory> is the amount of memory to allocate to the instance in megabytes.

If kernel_cmdline is specified, it will be passed to the kernel as the kernel command line. When specified, kernel_path must also be specified. The daily_image and released_image calls will automatically download the kernel for the image, so if these calls have been used to obtain the image_id, the kernel_path is not required.

By default, pycloudlib will create a seed iso for the instance in order to let cloud-init configure the instance. If no_seed_iso is set to True, pycloudlib will not create a seed iso. This may be useful when using the kernel_cmdline behavior or when using an image that already has keys and/or passwords configured.

Ports

Pycloudlib will allocate two local ports per instance to handle SSH and telnet traffic. These ports are allocated in the range 18000-18100. This information is logged to the console when launching an instance as well as using the API via the port and telnet_port instance attributes.

The telnet port allows full serial interaction for cases where SSH is not available or not working.

Networking

Pycloudlib does not configure networking outside of mapping ports. By default, the VM guest default route will be 10.0.2.2 if the VM needs to access the host.

QEMU Machine Protocol

Under the hood, Pycloudlib uses the QEMU Machine Protocol (QMP) to interact with running VMs. While this is generally meant to be an implementation detail, if needed, the socket file may be found in the working_dir with the name qmp-socket.

A QEMU Monitor interface is not exposed.