CLOUD-HYPERVISOR(1)

📦 version 53.0, in ubuntu stonking

💅 CLOUD-HYPERVISOR 💅

okay bestie, welcome to the cloud-hypervisor manual page — she's a User Commands girlie (that's section 1 for the manpage girlies keeping score) and she is literally about to run an entire virtual machine for you. no cap.

✨ NAME ✨

cloud-hypervisor — launch a cloud-hypervisor virtual machine monitor 🫶

🎀 SYNOPSIS 🎀

cloud-hypervisor [OPTIONS]

that's it. that's the whole vibe. you give her [OPTIONS] and she gives you a whole ass virtual machine. iconic behavior fr fr.

🦋 DESCRIPTION 🦋

okay so. cloud-hypervisor is an open source Virtual Machine Monitor — a VMM, which is just the fancy name for the thing that runs your VMs — and she runs on top of KVM. putting it simply: KVM does the heavy hardware lifting, and cloud-hypervisor is the main character directing the whole production. 👑

her whole thing, her mission, is running modern, cloud workloads with paravirtualised I/O (virtio). and when she says modern she means it — she's targeting recent 64-bit CPUs on x86_64 and aarch64 architectures. so if you're out here on some ancient 32-bit situation… bestie she's not the one. 🙈

and here's the part that's genuinely giving main character energy: you can configure the whole VMM entirely via command-line options, OR you can manage her at runtime through an HTTP API that's exposed over a UNIX domain socket. so like, set her up from the terminal and then keep steering her while she's running?? we love a flexible queen. 💅

oh and if you wanna talk to that HTTP API, check out ch-remote(1) — that's the bestie who handles the runtime management convo. iykyk. ✨

✨ OPTIONS ✨

okay bestie, buckle up 🎀 this is the part where Cloud Hypervisor shows you literally everything it can do, and it can do a LOT. every single flag, every value, every default, all of it — no skips, no "you'll figure it out", fr fr.

  • --api-socket path=<path>|fd=<fd> — the HTTP API socket, aka a UNIX domain socket 🫶. hand it either a path=<path> on the filesystem or an fd=<fd>, which is a file descriptor you already have open.
  • --balloon params — balloon device parameters 🎈 (the memory that goes pshhh and inflates/deflates in the guest). Syntax: size=<balloon_size>,deflate_on_oom=on|off,free_page_reporting=on|off,iommu=on|off,id=<device_id>,pci_segment=<segment_id>,pci_device_id=<pci_slot>
  • --cmdline string — the kernel command line you're passing straight to the guest 💻. yes, that string, exactly.
  • --console params — control the (virtio) console setup 🌸. Syntax: off|null|pty|tty|file=<path>,iommu=on|off,id=<device_id>,pci_segment=<segment_id>,pci_device_id=<pci_slot>. Default is tty, bestie.
  • --cpus params — vCPU config, aka how many little brains your VM gets 🧠✨. Syntax: boot=<boot_vcpus>,max=<max_vcpus>,topology=<threads_per_core>:<cores_per_die>:<dies_per_package>:<packages>,kvm_hyperv=on|off,max_phys_bits=<maximum_number_of_physical_bits>,affinity=<list_of_vcpus_with_their_associated_cpuset>,features=<list_of_features_to_enable>,nested=on|off,core_scheduling=vm|vcpu|off. Default: boot=1,max_phys_bits=46.
  • --debug-console params — debug console config, the ✨extra✨ little channel for debugging. Syntax: off|pty|tty|file=<path>,iobase=<port_in_hex>. Default: off,iobase=0xe9.
  • --device params ... — direct device assignment (VFIO) parameters 🔥. this one may be specified multiple times. Syntax: path=<device_path>,fd=<vfio_cdev_fd>,iommu=on|off,id=<device_id>,pci_segment=<segment_id>,pci_device_id=<pci_slot>,x_nv_gpudirect_clique=<clique_id>,x_exclude_mmap_bars=[<bar>...]
  • --disk params ... — block device parameters 💾, and yes you can specify it multiple times. Syntax: path=<disk_image_path>,readonly=on|off,direct=on|off,iommu=on|off,num_queues=<number_of_queues>,queue_size=<size_of_each_queue>,vhost_user=on|off,socket=<vhost_user_socket_path>,bw_size=<bytes>,bw_one_time_burst=<bytes>,bw_refill_time=<ms>,ops_size=<io_ops>,ops_one_time_burst=<io_ops>,ops_refill_time=<ms>,id=<device_id>,pci_segment=<segment_id>,pci_device_id=<pci_slot>,rate_limit_group=<group_id>,queue_affinity=<list_of_queue_indices_with_their_associated_cpuset>,serial=<serial_number>,backing_files=on|off,sparse=on|off,image_type=<raw,qcow2,vhd,vhdx>,lock_granularity=byte-range|full
  • --event-monitor path=<path>|fd=<fd> — where the event monitor writes its output 👀. give it either a file path=<path> or a file fd=<fd>, and that's where events get reported.
  • --firmware path — path to the firmware, loaded the architecture-specific way (think UEFI) 🌈.
  • --fs params ... — virtio-fs device parameters 🍓. may be specified multiple times. Syntax: tag=<tag_name>,socket=<socket_path>,num_queues=<number_of_queues>,queue_size=<size_of_each_queue>,id=<device_id>,pci_segment=<segment_id>,pci_device_id=<pci_slot>
  • --generic-vhost-user params ... — generic vhost-user device parameters 🦋. may be specified multiple times. Syntax: virtio_id=<ID_or_name>,socket=<socket_path>,queue_sizes=<list_of_queue_sizes>,id=<device_id>,pci_segment=<segment_id>,pci_device_id=<pci_slot>
  • --initramfs path — path to an initramfs image to load into the guest 📦.
  • --kernel path — path to a kernel or firmware that supports a PVH entry point (like vmlinux) or the architecture equivalent 🐧.
  • --landlock — turn on Landlock-based filesystem sandboxing 🔒. yes, it's giving secure.
  • --landlock-rules params ... — Landlock rule parameters 🧚, may be specified multiple times. Syntax: path=<path/to/{file/dir}>,access=[rw]
  • --log-file path — where the log goes 📝. if you don't specify it, standard error gets it instead.
  • --log-format format — the log format string 💅. common tokens include {boottime}, {wallclock}, {glog}, {localglog}, {thread}, {level}, {location}, {msg}. Default: "cloud-hypervisor: {boottime}s: <{thread}> {level}:{location} -- {msg}".
  • --memory params — guest memory configuration, the main character of resource allocation 👑. Syntax: size=<guest_memory_size>,mergeable=on|off,shared=on|off,hugepages=on|off,hugepage_size=<hugepage_size>,hotplug_method=acpi|virtio-mem,hotplug_size=<hotpluggable_memory_size>,hotplugged_size=<hotplugged_memory_size>,prefault=on|off,reserve=on|off,thp=on|off. Default: size=512M.
  • --memory-zone params ... — user-defined memory zone parameters, may be specified multiple times 🗂️. Syntax: size=<guest_memory_region_size>,file=<backing_file>,shared=on|off,hugepages=on|off,hugepage_size=<hugepage_size>,host_numa_node=<node_id>,id=<zone_identifier>,hotplug_size=<hotpluggable_memory_size>,hotplugged_size=<hotplugged_memory_size>,prefault=on|off,reserve=on|off
  • --net params ... — network device parameters, may be specified multiple times 🌐✨. Syntax: tap=<if_name>,ip=<ip_addr>,mask=<net_mask>,mac=<mac_addr>,fd=<[fd1,fd2,...]>,iommu=on|off,num_queues=<number_of_queues>,queue_size=<size_of_each_queue>,id=<device_id>,vhost_user=<vhost_user_enable>,socket=<vhost_user_socket_path>,vhost_mode=client|server,bw_size=<bytes>,bw_one_time_burst=<bytes>,bw_refill_time=<ms>,ops_size=<io_ops>,ops_one_time_burst=<io_ops>,ops_refill_time=<ms>,pci_segment=<segment_id>,pci_device_id=<pci_slot>,offload_tso=on|off,offload_ufo=on|off,offload_csum=on|off
  • --no-shutdown — do not exit the VMM process when the guest shuts down 🙈. super handy for VMs you expect to reboot or that get managed externally.
  • --numa params ... — NUMA node configuration, may be specified multiple times 🧩. Syntax: guest_numa_id=<node_id>,cpus=<cpus_id>,distances=<list_of_distances_to_destination_nodes>,device_id=<device_id>,memory_zones=<list_of_memory_zones>,pci_segments=<list_of_pci_segments>
  • --pci-segment params ... — PCI segment parameters, may be specified multiple times 🚌. Syntax: pci_segment=<segment_id>,mmio32_aperture_weight=<scale>,mmio64_aperture_weight=<scale>
  • --platform params — platform configuration parameters, all the DMI-flavored goodies 🎀. Syntax: num_pci_segments=<num_pci_segments>,iommu_segments=<list_of_segments>,iommu_address_width=<bits>,iommufd=on|off,iommufd_fd=<fd>,vfio_p2p_dma=on|off,system_manufacturer=<dmi_system_manufacturer>,system_product_name=<dmi_system_product_name>,system_version=<dmi_system_version>,system_serial_number=<dmi_system_serial_number>,system_uuid=<dmi_system_uuid>,system_sku_number=<dmi_system_sku_number>,system_family=<dmi_system_family>,oem_strings=<list_of_strings>,chassis_asset_tag=<dmi_chassis_asset_tag>
  • --pmem params ... — persistent memory device parameters 💜, may be specified multiple times. Syntax: file=<backing_file_path>,size=<persistent_memory_size>,iommu=on|off,discard_writes=on|off,id=<device_id>,pci_segment=<segment_id>,pci_device_id=<pci_slot>
  • --pvpanic — enables the pvpanic device 😱, so the guest can tell the host about kernel panics. very "not me screaming for help" energy.
  • --rate-limit-group params ... — rate limit group parameters ⏳, may be specified multiple times. Syntax: bw_size=<bytes>,bw_one_time_burst=<bytes>,bw_refill_time=<ms>,ops_size=<io_ops>,ops_one_time_burst=<io_ops>,ops_refill_time=<ms>,id=<device_id>
  • --restore params — restore a VM from a snapshot 🫧. Syntax: source_url=<source_url>,prefault=on|off,memory_restore_mode=copy|ondemand,net_fds=<list_of_net_ids_with_their_associated_fds>,resume=true|false

so source_url has to be a valid URL (like file:///foo/bar or tcp://192.168.1.10/foo), periodt. prefault controls eager prefaulting for the copy-based restore path, and it's disabled by default. memory_restore_mode=copy preserves the existing eager read-copy restore behavior, while memory_restore_mode=ondemand enables lazy demand paging — and heads up bestie, that one requires userfaultfd ⚠️. net_fds supplies new file descriptors for net devices backed by FDs. and resume controls whether the VM is resumed right after restore.

  • --rng params — random number generator parameters 🎲. Syntax: src=<entropy_source_path>,iommu=on|off,pci_segment=<segment_id>,pci_device_id=<pci_slot>. Default: src=/dev/urandom.
  • --rtc [params] — virtio RTC device parameters ⏰. just passing --rtc with no arguments at all enables the device with default settings, slay. Syntax: iommu=on|off,id=<device_id>,pci_segment=<segment_id>,pci_device_id=<pci_slot>
  • --seccomp true|false|log — seccomp filtering mode 🛡️. when true, system calls the VMM doesn't need are blocked. when log, violations get logged but not blocked. Default: true.
  • --serial mode — serial port configuration 🔌. Syntax: off|null|pty|tty|file=<path>|socket=<path>. Default: null.
  • --tpm params — TPM device parameters 🔐. note: this requires an external swtpm(8) instance. Syntax: socket=</path/to/a/socket>.
  • --user-device params ... — userspace device parameters, may be specified multiple times 🧸. Syntax: socket=<socket_path>,id=<device_id>,pci_segment=<segment_id>,pci_device_id=<pci_slot>.
  • -v, -vv, -vvv — crank up the verbosity of debugging output 🔊. you can repeat it for even more detail. more v's, more tea.
  • --vdpa params ... — vDPA device parameters, may be specified multiple times 🌀. Syntax: path=<device_path>,num_queues=<number_of_queues>,iommu=on|off,id=<device_id>,pci_segment=<segment_id>,pci_device_id=<pci_slot>
  • -V, --version — print version info and exit 🏷️.
  • --vsock params — virtio VSOCK device parameters 📞. Syntax: cid=<context_id>,socket=<socket_path>,iommu=on|off,id=<device_id>,pci_segment=<segment_id>,pci_device_id=<pci_slot>
  • --watchdog — enable the virtio-watchdog device 🐕. someone's gotta keep watch.
  • -h, --help — print a help summary and exit 🙋‍♀️. the classic.

✨ EXAMPLES ✨

Okay bestie, this is the part where it all comes together 💖. Two full recipes, copy-paste energy, let's gooo.

🐧 Boot a VM with a kernel image and a root disk

Classic direct-boot moment. No firmware, no drama, just kernel + rootfs:

cloud-hypervisor \
    --kernel /path/to/vmlinux \
    --disk path=/path/to/rootfs.img \
    --cpus boot=2 \
    --memory size=1G \
    --cmdline "root=/dev/vda1 console=hvc0" \
    --api-socket path=/tmp/ch.sock

Look at her. Two CPUs, one gig of RAM, a root disk, and a kernel that knows exactly where to find its root via root=/dev/vda1 and where to yell its logs via console=hvc0 🔥. And --api-socket drops a socket at /tmp/ch.sock so you can talk to her later like the main character she is. Periodt.

🦋 Boot a VM using UEFI firmware

Now the glow-up version — firmware instead of a raw kernel, plus networking because we're connected like that:

cloud-hypervisor \
    --firmware /usr/share/OVMF/OVMF_CODE.fd \
    --disk path=/path/to/disk.qcow2 \
    --cpus boot=4 \
    --memory size=4G \
    --net tap=tap0,mac=12:34:56:78:90:ab \
    --api-socket path=/tmp/ch.sock

Four CPUs, four gigs, a qcow2 disk, OVMF firmware doing its thing, and a tap interface named tap0 with the MAC 12:34:56:78:90:ab so she's on the network and everyone knows her name 💅. Same API socket, same /tmp/ch.sock, same iconic energy.

Not me noticing both examples end with --api-socket path=/tmp/ch.sock — because managing your VM over a socket is just how it's done, iykyk 🎀

🌈 SEE ALSO 🌈

Go read these next, bestie, they're the friend group: 🫶

Project documentation: https://www.cloudhypervisor.org/ ⭐

👑 AUTHORS 👑

The Cloud Hypervisor Authors. That's the whole squad, no individual shoutouts, just the collective. Iconic behaviour honestly 💜.

💖 LICENSE 💖

Apache-2.0 AND BSD-3-Clause — both of them, together, as a duo. Slay.

And that's the whole page, babe!! This was cloud-hypervisor 52.0.0, dated 2025-07-01, and you've officially read the entire CLOUD-HYPERVISOR(1) manual like the certified Unix main character you are. 🦋✨ Go boot something. 💅🌸

📦 where this page comes from