mirror of
https://github.com/threefoldtech/mycelium.git
synced 2026-05-14 19:35:10 +00:00
Lee Smet
99 lines
2.6 KiB
Markdown
99 lines
2.6 KiB
Markdown
# Vsock transport
|
|
|
|
Mycelium supports [VM sockets (vsock)](https://man7.org/linux/man-pages/man7/vsock.7.html) 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
mycelium --vsock-listen-port 9651
|
|
```
|
|
|
|
On the **guest VM**, connect to the host (CID `2`) as a static peer:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
mycelium --vsock-listen-port 9651
|
|
```
|
|
|
|
On the **host**, connect to the guest using its CID (e.g. `42`):
|
|
|
|
```sh
|
|
mycelium --peers vsock://42:9651
|
|
```
|
|
|
|
## Configuration file
|
|
|
|
Vsock settings can also be placed in the mycelium configuration file:
|
|
|
|
```toml
|
|
# 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:
|
|
|
|
```sh
|
|
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.
|