VHOST-DEVICE-VSOCK(1)

NAME
vhost-device-vsock - A virtio-vsock device using the vhost-user protocol

SYNOPSIS
vhost-device-vsock --socket SOCKET --uds-path UDS_PATH

DESCRIPTION
The vhost-device-vsock utility launches a daemon listening to SOCKET for incoming connections from vhost-user front-ends. Upon successful connection and protocol negotiation, it starts a vhost-user backend instance. The functionality of a VIRTIO vsock device is provided using the specified unix socket, UDS_PATH , to which a host-side application connects to.

--help | -h
    Print help information.

--version | -V
    Print version information.

--guest-cid GUEST_CID
    Context identifier of the guest which uniquely identifies the device for its lifetime [default: 3]

--socket SOCKET
    Unix socket to which a hypervisor connects to and sets up the control path with the device

--uds-path UDS_PATH
    Unix socket to which a host-side application connects to

--tx-buffer-size TX_BUFFER_SIZE
    The size of the buffer used for the TX virtqueue [default: 65536]

--queue-size QUEUE_SIZE
    The size of the vring queue [default: 1024]

--groups GROUPS
    The list of group names to which the device belongs. A group is a set of devices that allow sibling communication between their guests. [default: "default"]

--config CONFIG
    Load from a given configuration file

    NOTE: conflicts with --vm

--vm VM
    Device parameters corresponding to a VM in the form of comma separated key=value pairs. Multiple instances of this option can be provided to configure devices for multiple guests. The allowed keys are:
    1.  guest_cid
    2.  socket
    3.  uds_path
    4.  tx_buffer_size
    5.  queue_size
    6.  group
    NOTE: conflicts with --config

EXIT STATUS

EXAMPLES

  Run the vhost-device-vsock device

    vhost-device-vsock \
     --vm \
    guest_cid=<GUEST_CID>,\
    socket=<SOCKET_PATH>,\
    uds-path=<UDS_PATH>\
    [,tx-buffer-size=<TX_SIZE>][,queue-size=<QUEUE_SIZE>][,groups=<GROUPS_LIST>]

Specify the `--vm` argument multiple times to specify multiple devices like this:

    vhost-device-vsock \
    --vm guest-cid=3,socket=/tmp/vhost3.socket,uds-path=/tmp/vm3.vsock,groups=group1+groupA \
    --vm guest-cid=4,socket=/tmp/vhost4.socket,uds-path=/tmp/vm4.vsock,tx-buffer-size=32768,queue-size=256

Or use a configuration file:

    vhost-device-vsock --config=<path to the local yaml configuration file>

Configuration file example in yaml format:

    vms:
        - guest_cid: 3
          socket: /tmp/vhost3.socket
          uds_path: /tmp/vm3.sock
          tx_buffer_size: 65536
          queue_size: 1024
          groups: group1+groupA
        - guest_cid: 4
          socket: /tmp/vhost4.socket
          uds_path: /tmp/vm4.sock
          tx_buffer_size: 32768
          queue_size: 256
          groups: group2+groupB

  Run VMM (e.g. QEMU)

    qemu-system-x86_64 \
      <normal QEMU options> \
      -object memory-backend-memfd,id=mem0,size=<Guest RAM size> \ # size == -m size
      -machine <machine options>,memory-backend=mem0 \
      -chardev socket,id=char0,reconnect=0,path=<vhost-user socket path> \
      -device vhost-user-vsock-pci,chardev=char0

NOTE: With QEMU you have to use a shareable memory-backend such as memory-backend-memfd

  Working example

    shell1$ vhost-device-vsock --vm guest-cid=4,uds-path=/tmp/vm4.vsock,socket=/tmp/vhost4.socket

or if you want to configure the TX buffer size and vring queue size

    shell1$ vhost-device-vsock --vm guest-cid=4,uds-path=/tmp/vm4.vsock,socket=/tmp/vhost4.socket,tx-buffer-size=65536,queue-size=1024

    shell2$ qemu-system-x86_64 \
              -drive file=vm.qcow2,format=qcow2,if=virtio -smp 2 \
              -object memory-backend-memfd,id=mem0,size=512M \
              -machine q35,accel=kvm,memory-backend=mem0 \
              -chardev socket,id=char0,reconnect=0,path=/tmp/vhost4.socket \
              -device vhost-user-vsock-pci,chardev=char0

STANDARDS
-   Virtual I/O Device (VIRTIO), Version 1.2, OASIS, https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html, July 01, 2022.
-   Vhost-user Protocol, Unversioned, QEMU Project, https://qemu.readthedocs.io/en/v9.0.0/interop/vhost-user.html, Undated.

AUTHORS
Copyright 2023–2024
Harshavardhan Unnibhavi <harshanavkis@gmail.com>>
Stefano Garzarella <sgarzare@redhat.com>>

Released under Apache-2.0 OR BSD-3-Clause. ( See files LICENSE-APACHE , LICENSE-BSD-3-Clause for full copyright and warranty notices.)

  Links
Main repository: https://github.com/rust-vmm/vhost-device
on crates.io: https://crates.io/crates/vhost-device-vsock