microsoft/cloud-hypervisor

microsoft/cloud-hypervisor

Description: This repository contains code that's not yet upstreamed or Microsoft specific. Please contribute directly to the upstream project.

Language: Rust

Stars: 10

Forks: 5

Open issues: 1

Created: 2024-02-09T19:35:58Z

Pushed: 2026-08-20T05:26:40Z

Default branch: msft-main-3.0

Fork: yes

Parent repository: cloud-hypervisor/cloud-hypervisor

Archived: no

README:

• [1. What is Cloud Hypervisor?](#1-what-is-cloud-hypervisor)
• [Objectives](#objectives)
• [High Level](#high-level)
• [Architectures](#architectures)
• [Guest OS](#guest-os)
• [2. Getting Started](#2-getting-started)
• [Host OS](#host-os)
• [Use Pre-built Binaries](#use-pre-built-binaries)
• [Packages](#packages)
• [Building from Source](#building-from-source)
• [Booting Linux](#booting-linux)
• [Firmware Booting](#firmware-booting)
• [Custom Kernel and Disk Image](#custom-kernel-and-disk-image)
• [Building your Kernel](#building-your-kernel)
• [Disk image](#disk-image)
• [Booting the guest VM](#booting-the-guest-vm)
• [3. Status](#3-status)
• [Hot Plug](#hot-plug)
• [Device Model](#device-model)
• [Roadmap](#roadmap)
• [4. Relationship with _Rust VMM_ Project](#4-relationship-with-rust-vmm-project)
• [Differences with Firecracker and crosvm](#differences-with-firecracker-and-crosvm)
• [5. Community](#5-community)
• [Contribute](#contribute)
• [Slack](#slack)
• [Mailing list](#mailing-list)
• [Security issues](#security-issues)

1. What is Cloud Hypervisor?

Cloud Hypervisor is an open source Virtual Machine Monitor (VMM) that runs on top of the KVM hypervisor and the Microsoft Hypervisor (MSHV).

The project focuses on running modern, _Cloud Workloads_, on specific, common, hardware architectures. In this case _Cloud Workloads_ refers to those that are run by customers inside a Cloud Service Provider. This means modern operating systems with most I/O handled by paravirtualised devices (e.g. _virtio_), no requirement for legacy devices, and 64-bit CPUs.

Cloud Hypervisor is implemented in Rust and is based on the Rust VMM crates.

Objectives

High Level

• Runs on KVM or MSHV
• Minimal emulation
• Low latency
• Low memory footprint
• Low complexity
• High performance
• Small attack surface
• 64-bit support only
• CPU, memory, PCI hotplug
• Machine to machine migration

Architectures

Cloud Hypervisor supports the x86-64 and AArch64 architectures. There are minor differences in functionality between the two architectures (see #1125).

Guest OS

Cloud Hypervisor supports 64-bit Linux and Windows 10/Windows Server 2019.

2. Getting Started

The following sections describe how to build and run Cloud Hypervisor.

Prerequisites for AArch64

• AArch64 servers (recommended) or development boards equipped with the GICv3

interrupt controller.

Host OS

For required KVM functionality and adequate performance the recommended host kernel version is 5.13. The majority of the CI currently tests with kernel version 5.15.

Use Pre-built Binaries

The recommended approach to getting started with Cloud Hypervisor is by using a pre-built binary. Binaries are available for the latest release. Use cloud-hypervisor-static for x86-64 or cloud-hypervisor-static-aarch64 for AArch64 platform.

Packages

For convenience, packages are also available targeting some popular Linux distributions. This is thanks to the Open Build Service. The OBS README explains how to enable the repository in a supported Linux distribution and install Cloud Hypervisor and accompanying packages. Please report any packaging issues in the obs-packaging repository.

Building from Source

Please see the [instructions for building from source](docs/building.md) if you do not wish to use the pre-built binaries.

Booting Linux

Cloud Hypervisor supports direct kernel boot (the x86-64 kernel requires the kernel built with PVH support or a bzImage) or booting via a firmware (either Rust Hypervisor Firmware or an edk2 UEFI firmware called CLOUDHV / CLOUDHV_EFI.)

Binary builds of the firmware files are available for the latest release of Rust Hypervisor Firmware and our edk2 repository

The choice of firmware depends on your guest OS choice; some experimentation may be required.

Firmware Booting

Cloud Hypervisor supports booting disk images containing all needed components to run cloud workloads, a.k.a. cloud images.

The following sample commands will download an Ubuntu Cloud image, converting it into a format that Cloud Hypervisor can use and a firmware to boot the image with.

$ wget https://cloud-images.ubuntu.com/focal/current/focal-server-cloudimg-amd64.img
$ qemu-img convert -p -f qcow2 -O raw focal-server-cloudimg-amd64.img focal-server-cloudimg-amd64.raw
$ wget https://github.com/cloud-hypervisor/rust-hypervisor-firmware/releases/download/0.4.2/hypervisor-fw

The Ubuntu cloud images do not ship with a default password so it necessary to use a cloud-init disk image to customise the image on the first boot. A basic cloud-init image is generated by this [script](scripts/create-cloud-init.sh). This seeds the image with a default username/password of cloud/cloud123. It is only necessary to add this disk image on the first boot. Script also assigns default IP address using test_data/cloud-init/ubuntu/local/network-config details with --net "mac=12:34:56:78:90:ab,tap=" option. Then the matching mac address interface will be enabled as per network-config details.

$ sudo setcap cap_net_admin+ep ./cloud-hypervisor
$ ./create-cloud-init.sh
$ ./cloud-hypervisor \
--kernel ./hypervisor-fw \
--disk path=focal-server-cloudimg-amd64.raw path=/tmp/ubuntu-cloudinit.img \
--cpus boot=4 \
--memory size=1024M \
--net "tap=,mac=,ip=,mask="

If access to the firmware messages or interaction with the boot loader (e.g. GRUB) is required then it necessary to...