1# VSOCK support 2 3VSOCK provides a way for guest and host to communicate through a socket. `cloud-hypervisor` only supports stream VSOCK sockets. 4 5The `virtio-vsock` is based on the [Firecracker](https://github.com/firecracker-microvm/firecracker/blob/main/docs/vsock.md) implementation, where additional details can be found. 6 7## What is a CID? 8 9CID is a 32-bit context identifier describing the source or destination. In combination with the port, the complete addressing can be achieved to describe multiple listeners running on the same machine. 10 11The table below depicts the well known CID values: 12 13| CID | Description | 14|-----|-------------| 15| -1 | Random CID | 16| 0 | Hypervisor | 17| 1 | Loopback | 18| 2 | Host | 19 20## Prerequisites 21 22### Kernel Requirements 23 24Host kernel: CONFIG_VHOST_VSOCK 25 26Guest kernel: CONFIG_VIRTIO_VSOCKETS 27 28### Nested VM support 29 30Linux __v5.5__ or newer is required for the L1 VM. 31 32### Loopback support 33 34Linux __v5.6__ or newer is required. 35 36## Establishing VSOCK Connection 37 38VSOCK device becomes available with `--vsock` option passed by the VM start. Cloud Hypervisor can be invoked for instance as below: 39 40```bash 41cloud-hypervisor \ 42 --cpus boot=1 \ 43 --memory size=4G \ 44 --firmware CLOUDHV.fd \ 45 --disk path=jammy-server-cloudimg.raw \ 46 --vsock cid=3,socket=/tmp/ch.vsock 47``` 48 49The examples use __socat__ `>=1.7.4` to illustrate the VSOCK functionality. However, there are other tools supporting VSOCK, like [ncat](https://stefano-garzarella.github.io/posts/2019-11-08-kvmforum-2019-vsock/). 50 51### Connecting from Host to Guest 52 53The guest starts to listen on the defined port: 54 55`$ socat - VSOCK-LISTEN:1234` 56 57Once the guest is listening, the host can send data: 58 59`echo -e "CONNECT 1234\\nHello from host!" | socat - UNIX-CONNECT:/tmp/ch.vsock 60 61Note the string `CONNECT <port>` prepended to the actual data. It is possible for the guest to start listening on different ports, thus the specific command is needed to instruct VSOCK to which listener the host wants to connect. It needs to be sent once per connection. Once the connection established, data transfers can take place directly. 62 63### Connecting from Guest to Host 64 65This first requires a listening UNIX socket on the host side. The UNIX socket path has to be constructed by using the socket path used at the VM launch time with appended `_` and the port number to be used on the guest side. As in the example above, if we'd intended to connect from the guest to the port `1234`, the Unix socket path on the host side would be `/tmp/ch.vsock_1234`. 66 67Also note that the CID used on the guest side is the well known CID value `2`. 68 69Listening on the host side: 70 71`$ socat - UNIX-LISTEN:/tmp/ch.vsock_1234` 72 73From the guest: 74 75`$ echo -e "Hello from guest!" | socat - VSOCK-CONNECT:2:1234` 76 77## Links 78 79- [virtio-vsock in QEMU, Firecracker and Linux: Status, Performance and Challenges](https://kvmforum2019.sched.com/event/TmwK) 80- [Leveraging virtio-vsock in the cloud and containers](https://archive.fosdem.org/2021/schedule/event/vai_virtio_vsock/) 81- [VSOCK man page](https://manpages.ubuntu.com/manpages/focal/man7/vsock.7.html) 82- [https://stefano-garzarella.github.io/posts/2020-02-20-vsock-nested-vms-loopback/](https://stefano-garzarella.github.io/posts/2020-02-20-vsock-nested-vms-loopback/) 83- [https://github.com/firecracker-microvm/firecracker/blob/main/docs/vsock.md](https://github.com/firecracker-microvm/firecracker/blob/main/docs/vsock.md) 84 85