vhost-device-vsock - Man Page

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

The vhost-device-vsock utility exits 0 on success, and >0 if an error occurs.

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

Authors

Copyright 2023–2024

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

Info

July 24, 2024