vsock (7) - Linux Man Pages
vsock: Linux VSOCK address family
NAME
vsock - Linux VSOCK address family
SYNOPSIS
#include <sys/socket.h>#include <linux/vm_sockets.h>
stream_socket = socket(AF_VSOCK, SOCK_STREAM, 0);
datagram_socket = socket(AF_VSOCK, SOCK_DGRAM, 0);
DESCRIPTION
The VSOCK address family facilitates communication between virtual machines and the host they are running on. This address family is used by guest agents and hypervisor services that need a communications channel that is independent of virtual machine network configuration.Valid socket types are SOCK_STREAM and SOCK_DGRAM. SOCK_STREAM provides connection-oriented byte streams with guaranteed, in-order delivery. SOCK_DGRAM provides a connectionless datagram packet service with best-effort delivery and best-effort ordering. Availability of these socket types is dependent on the underlying hypervisor.
A new socket is created with
socket(AF_VSOCK, socket_type, 0);
When a process wants to establish a connection, it calls connect(2) with a given destination socket address. The socket is automatically bound to a free port if unbound.
A process can listen for incoming connections by first binding to a socket address using bind(2) and then calling listen(2).
Data is transmitted using the send(2) or write(2) families of system calls and data is received using the recv(2) or read(2) families of system calls.
Address format
A socket address is defined as a combination of a 32-bit Context Identifier (CID) and a 32-bit port number. The CID identifies the source or destination, which is either a virtual machine or the host. The port number differentiates between multiple services running on a single machine.
struct sockaddr_vm {
svm_family
is always set to
AF_VSOCK.
svm_reserved1
is always set to 0.
svm_port
contains the port number in host byte order.
The port numbers below 1024 are called
privileged ports.
Only a process with the
CAP_NET_BIND_SERVICE
capability may
bind(2)
to these port numbers.
svm_zero
must be zero-filled.
There are several special addresses:
VMADDR_CID_ANY
(-1U)
means any address for binding;
VMADDR_CID_HYPERVISOR
(0) is reserved for services built into the hypervisor;
VMADDR_CID_RESERVED
(1) must not be used;
VMADDR_CID_HOST
(2)
is the well-known address of the host.
The special constant
VMADDR_PORT_ANY
(-1U)
means any port number for binding.
The local CID may change across live migration if the old CID is
not available on the new host.
Bound sockets are automatically updated to the new CID.
Live migration
Sockets are affected by live migration of virtual machines.
Connected
SOCK_STREAM
sockets become disconnected when the virtual machine migrates to a new host.
Applications must reconnect when this happens.
Ioctls
ERRORS
VERSIONS
Support for VMware (VMCI) has been available since Linux 3.9.
KVM (virtio) is supported since Linux 4.8.
Hyper-V is supported since Linux 4.14.
COLOPHON
This page is part of release 5.05 of the Linux
man-pages
project.
A description of the project,
information about reporting bugs,
and the latest version of this page,
can be found at
https://www.kernel.org/doc/man-pages/.