VHOST-DEVICE-VSOCK(1)

📦 version 0.3.0, in fedora 43, fedora 44, nixpkgs unstable, ubuntu stonking

✨ NAME ✨

okay so bestie, say hi to vhost-device-vsock — a virtio-vsock device that speaks the vhost-user protocol 💅 it lives in section 1 of the General Commands Manual, so it's a real grown-up command, not some library situation.

🦋 SYNOPSIS 🦋

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

🌸 DESCRIPTION 🌸

The vhost-device-vsock utility launches a daemon that sits there listening on SOCKET for incoming connections from vhost-user front-ends. Obsessed. The moment a connection lands and protocol negotiation finishes, it spins up a vhost-user backend instance. All the VIRTIO vsock device functionality is served up through the unix socket you name as UDS_PATH, and that's the socket a host-side application connects to. 🫶

  • --help, -h — prints the help information, bestie. the classic.
  • --version, -V — prints version information ✨
  • --guest-cid GUEST_CID — the context identifier of the guest, which uniquely identifies the device for its entire lifetime. default is 3.
  • --socket SOCKET — the unix socket a hypervisor connects to so it can set up the control path with the device 🔥
  • --uds-path UDS_PATH — the unix socket a host-side application connects to 💖
  • --tx-buffer-size TX_BUFFER_SIZE — how big the buffer used for the TX virtqueue is. default: 65536.
  • --queue-size QUEUE_SIZE — the size of the vring queue. default: 1024.
  • --groups GROUPS — the list of group names this device belongs to. a group is a set of devices that let sibling guests talk to each other 👯 default: "default".
  • --config CONFIG — load everything from a given configuration file.
NOTE: this conflicts with --vm. pick one, bestie, you can't have both 😭
  • --vm VM — device parameters for a VM, written as comma separated key=value pairs. you can pass this option multiple times 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: this conflicts with --config. yeah, same deal. one or the other 💀

🌈 EXIT STATUS 🌈

The vhost-device-vsock utility exits 0 when it succeeds, and >0 if an error occurs. no in-between, it's giving binary 💅

🎀 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. no cap, it will not work otherwise.

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

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

and that's the whole page, bestie 🩷 this one came from the Debian folks, dated July 24, 2024, and yeah it's the VHOST-DEVICE-VSOCK(1) manual — go configure some vsock devices, you're literally the main character now 🌈💅✨

📦 where this page comes from