CH-REMOTE(1)

📦 version 53.0, in ubuntu stonking

💖 NAME 💖

okay bestie, meet ch-remote — the little command-line baddie that remotely controls a cloud-hypervisor VMM 🎀 (that's CH-REMOTE(1) in the manual, iykyk)

✨ SYNOPSIS ✨

ch-remote [OPTIONS] COMMAND [ARGS]

🌸 DESCRIPTION 🌸

so like, ch-remote is a command-line client (yes, a whole client, she's employed 💅) that talks to a running cloud-hypervisor(1) instance through its HTTP API socket 🔌

and the way that she can do so much, it's giving main character energy, fr fr:

  • query VM status 👀
  • hotplug devices 🔥
  • trigger lifecycle operations (boot, pause, resume, reboot, shutdown) 🦋
  • perform live migration ✈️
  • create or restore snapshots 📸

periodt. no cap.

🫶 OPTIONS 🫶

  • --api-socket path — path to the HTTP API UNIX domain socket of the target cloud-hypervisor(1) instance 🧦
  • -h, --help — print a help summary and exit (she's helpful like that 💜)
  • -V, --version — print version information and exit ⭐

👑 COMMANDS 👑

🌈 Lifecycle Commands

  • boot — boot a created VM. the VM must have been previously created with the create command 👶✨
  • pause — pause a running VM. all vCPUs are suspended ⏸️
  • resume — resume a previously paused VM ▶️
  • reboot — reboot the VM 🔄
  • shutdown — shutdown the VM (graceful guest-initiated shutdown) 🕊️
  • shutdown-vmm — shutdown the VMM process itself 💀 (not the guest — the whole dang VMM)
  • power-button — trigger an ACPI power button event in the VM, allowing the guest to handle the shutdown gracefully 🔘
  • nmi — trigger a Non-Maskable Interrupt (NMI) in the VM. useful for debugging guest hangs 🐛
  • delete — delete a VM and free its resources 🧹

🎀 VM Creation and Configuration

  • create [path] — create a VM from a JSON configuration file. if path is “-” or omitted, the configuration is read from standard input 📥
  • resize options — resize the VM resources 📐
    • --cpus count — new vCPU count
    • --memory size — new memory size in bytes (supports K/M/G suffix)
    • --balloon size — new balloon size in bytes (supports K/M/G suffix)
  • resize-disk options — resize an attached block device 💾
    • --disk id — disk device identifier
    • --size size — new disk size
  • resize-zone options — resize a memory zone 🗺️
    • --id zone_id — memory zone identifier
    • --size size — new memory zone size in bytes (supports K/M/G suffix)

🔥 Device Hotplug

  • add-device config — add a VFIO device 🧩 syntax:
path=<device_path>,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>...]
  • add-disk config — add a block device 💽 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>,id=<device_id>,
pci_segment=<segment_id>,pci_device_id=<pci_slot>
  • add-fs config — add a virtio-fs backed filesystem device 📁 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>
  • add-generic-vhost-user config — add a generic vhost-user device 🧚 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>
  • add-net config — add a network device 🌐 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=on|off,socket=<vhost_user_socket_path>,
vhost_mode=client|server,pci_segment=<segment_id>,
pci_device_id=<pci_slot>
  • add-pmem config — add a persistent memory device 🧠 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>
  • add-user-device config — add a userspace device 🛠️ syntax:
socket=<socket_path>,id=<device_id>,pci_segment=<segment_id>,pci_device_id=<pci_slot>.
  • add-vdpa config — add a vDPA device ⚡ syntax:
path=<device_path>,num_queues=<number_of_queues>,
iommu=on|off,id=<device_id>,
pci_segment=<segment_id>,pci_device_id=<pci_slot>
  • add-vsock config — add a vsock device 🧵 syntax:
cid=<context_id>,socket=<socket_path>,iommu=on|off,
id=<device_id>,pci_segment=<segment_id>,
pci_device_id=<pci_slot>
  • remove-device id — remove a VFIO or PCI device by its device identifier ✂️

🦋 Snapshot, Restore and Migration

  • snapshot destination_url — create a snapshot of the VM and save it to the given URL (e.g. file:///path/to/snapshot) 📸
  • restore config — restore a VM from a previously taken 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
  • send-migration config — initiate a live migration of the VM to a remote destination ✈️ syntax:
destination_url=<url>,local=on|off,
downtime_ms=<milliseconds>,timeout_s=<seconds>,
timeout_strategy=cancel|ignore,
connections=<amount>
  • receive-migration receiver_url — prepare to receive a VM migration on the given URL (e.g. tcp://0.0.0.0:1234) 📥
  • coredump file_path — create a coredump of the VM and write it to the specified file path 🫠

🔍 Monitoring

  • ping — ping the VMM to verify API server availability 🏓
  • info — display information about the current VM configuration and state 📋
  • counters — display performance counters from the VM 📊

🌟 EXAMPLES 🌟

ping a running VMM instance:

ch-remote --api-socket /tmp/ch.sock ping

boot a VM that was previously created:

ch-remote --api-socket /tmp/ch.sock boot

hotplug a disk to a running VM:

ch-remote --api-socket /tmp/ch.sock add-disk \
    path=/path/to/disk.raw,id=disk1

resize a VM to 4 vCPUs and 2G of memory:

ch-remote --api-socket /tmp/ch.sock resize \
    --cpus 4 --memory 2G

take a snapshot:

ch-remote --api-socket /tmp/ch.sock snapshot \
    file:///tmp/vm-snapshot

initiate a live migration:

ch-remote --api-socket /tmp/ch.sock send-migration \
    destination_url=tcp://192.168.1.10:1234

🧚 SEE ALSO 🧚

project documentation: https://www.cloudhypervisor.org/ 🌈

💜 AUTHORS 💜

the Cloud Hypervisor Authors 🫶 (yes, all of them, collectively iconic)

⭐ LICENSE ⭐

Apache-2.0 AND BSD-3-Clause 📜

and that's the whole page bestie 💅 — straight from cloud-hypervisor 52.0.0, dated 2025-07-01, manual page CH-REMOTE(1). go forth and control those VMMs remotely, you absolute legend 👑🦋

📦 where this page comes from