CLOUD-HYPERVISOR(1)

NAME
cloud-hypervisor - launch a cloud-hypervisor virtual machine monitor

SYNOPSIS
cloud-hypervisor [OPTIONS]

DESCRIPTION
cloud-hypervisor is an open source Virtual Machine Monitor (VMM) that runs on top of KVM. It focuses on running modern, cloud workloads with paravirtualised I/O (virtio), targeting recent 64-bit CPUs on x86_64 and aarch64 architectures.

The VMM can be configured entirely via command-line options or managed at runtime through an HTTP API exposed over a UNIX domain socket (see ch-remote(1)).

OPTIONS

--api-socket path=<path>|fd=<fd>
    HTTP API socket (UNIX domain socket). Specify either a filesystem path or an already-open file descriptor.

--balloon params
    Balloon device parameters. 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
    Kernel command line passed to the guest.

--console params
    Control (virtio) console configuration. Syntax:
    off|null|pty|tty|file=<path>,iommu=on|off,
    id=<device_id>,pci_segment=<segment_id>,
    pci_device_id=<pci_slot>
Default: tty.

--cpus params
    vCPU configuration. 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 configuration. Syntax: off|pty|tty|file=<path>,iobase=<port_in_hex>.
    Default: off,iobase=0xe9.

--device params ...
    Direct device assignment (VFIO) parameters. 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. May be specified 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>
    Event monitor output. Specify either a file path or a file descriptor where events are reported.

--firmware path
    Path to firmware that is loaded in an architecture-specific way (e.g. 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 supporting a PVH entry point (e.g. vmlinux) or architecture equivalent.

--landlock
    Enable Landlock-based filesystem sandboxing.

--landlock-rules params ...
    Landlock rule parameters. May be specified multiple times. Syntax: path=<path/to/{file/dir}>,access=[rw].

--log-file path
    Log file path. If not specified, standard error is used.

--log-format format
    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. 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. Useful for VMs that are expected to be rebooted or 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. 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
    Enable the pvpanic device, allowing the guest to notify the host of kernel panics.

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

    source_url should be a valid URL (e.g. file:///foo/bar or tcp://192.168.1.10/foo). prefault controls eager prefaulting for the copy-based restore path (disabled by default). memory_restore_mode=copy preserves existing eager read-copy restore behavior; memory_restore_mode=ondemand enables lazy demand paging (requires userfaultfd). net_fds supplies new file descriptors for net devices backed by FDs. resume controls whether the VM is resumed immediately 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. Passing --rtc with no arguments enables the device with default settings. 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 not required by the VMM are blocked. When log, violations are 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. 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
    Increase verbosity of debugging output. May be repeated for more detail.

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

-h, --help
    Print a help summary and exit.

EXAMPLES
Boot a VM with a kernel image and a root disk:

        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

Boot a VM using UEFI firmware:

        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

SEE ALSO
ch-remote(1), kvm(4), qemu-system-x86_64(1)

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

AUTHORS
The Cloud Hypervisor Authors.

LICENSE
Apache-2.0 AND BSD-3-Clause