CH-REMOTE(1)

NAME
ch-remote - remotely control a cloud-hypervisor VMM

SYNOPSIS
ch-remote [OPTIONS] COMMAND [ARGS]

DESCRIPTION
ch-remote is a command-line client that communicates with a running cloud-hypervisor(1) instance through its HTTP API socket. It can be used to query VM status, hotplug devices, trigger lifecycle operations (boot, pause, resume, reboot, shutdown), perform live migration, and create or restore snapshots.

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.

-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.

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
cloud-hypervisor(1), kvm(4)

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

AUTHORS
The Cloud Hypervisor Authors.

LICENSE
Apache-2.0 AND BSD-3-Clause