Skip to content

vsock.md

Latest commit

 

History

History
98 lines (65 loc) · 2.57 KB

vsock.md

File metadata and controls

98 lines (65 loc) · 2.57 KB

Vsock transport

Mycelium supports VM sockets (vsock) as a transport, allowing a mycelium node running inside a virtual machine to peer directly with a node running on the hypervisor host (or vice versa), without requiring a network interface.

Vsock is only available on Linux.

How it works

Vsock addresses a device by its Context ID (CID) and a port number, rather than an IP address. Key CID values:

CID Meaning
2 The hypervisor host
3 and up Guest VMs (assigned by the hypervisor)
4294967295 Any CID (used when listening)

A node that wants to accept inbound vsock connections binds to VMADDR_CID_ANY on a given port. The connecting side targets the peer's CID explicitly.

Starting a node with a vsock listener

Pass --vsock-listen-port when starting mycelium to accept inbound vsock connections:

mycelium --vsock-listen-port 9651

The listener binds on all CIDs (VMADDR_CID_ANY), so both host-to-guest and guest-to-host connections are accepted on the same port.

Connecting to a peer over vsock

Vsock peers are specified with the vsock:// scheme in the endpoint format:

vsock://<CID>:<port>

Example: guest VM connecting to the host

On the host, start mycelium with a vsock listener:

mycelium --vsock-listen-port 9651

On the guest VM, connect to the host (CID 2) as a static peer:

mycelium --peers vsock://2:9651

Example: host connecting to a guest VM

Find the guest's CID by consulting your hypervisor's documentation.

On the guest, start mycelium with a vsock listener:

mycelium --vsock-listen-port 9651

On the host, connect to the guest using its CID (e.g. 42):

mycelium --peers vsock://42:9651

Configuration file

Vsock settings can also be placed in the mycelium configuration file:

# Listen for inbound vsock connections on this port
vsock_listen_port = 9651

# Connect to the hypervisor host as a static peer
peers = ["vsock://2:9651"]

Combining vsock with other transports

Vsock and IP-based transports can be used simultaneously. A node can listen on both TCP and vsock at the same time, and peer over both:

mycelium --tcp-listen-port 9651 --vsock-listen-port 9651 --peers vsock://2:9651

Link cost

The vsock transport is assigned a lower link cost than any IP-based transport, reflecting that it is a local virtual channel with negligible latency. Mycelium will prefer a vsock path over an IP path when both are available to the same destination.