1VSOCK(7) Linux Programmer's Manual VSOCK(7)
2
6 vsock - Linux VSOCK address family
7
9 #include <sys/socket.h>
10 #include <linux/vm_sockets.h>
11 stream_socket = socket(AF_VSOCK, SOCK_STREAM, 0);
13 datagram_socket = socket(AF_VSOCK, SOCK_DGRAM, 0);
14
16 The VSOCK address family facilitates communication between virtual ma‐
17 chines and the host they are running on. This address family is used
18 by guest agents and hypervisor services that need a communications
19 channel that is independent of virtual machine network configuration.
20 Valid socket types are SOCK_STREAM and SOCK_DGRAM. SOCK_STREAM pro‐
22 vides connection-oriented byte streams with guaranteed, in-order deliv‐
23 ery. SOCK_DGRAM provides a connectionless datagram packet service with
24 best-effort delivery and best-effort ordering. Availability of these
25 socket types is dependent on the underlying hypervisor.
26 A new socket is created with
28 socket(AF_VSOCK, socket_type, 0);
30 When a process wants to establish a connection, it calls connect(2)
32 with a given destination socket address. The socket is automatically
33 bound to a free port if unbound.
34 A process can listen for incoming connections by first binding to a
36 socket address using bind(2) and then calling listen(2).
37 Data is transmitted using the send(2) or write(2) families of system
39 calls and data is received using the recv(2) or read(2) families of
40 system calls.
41 Address format
43 A socket address is defined as a combination of a 32-bit Context Iden‐
44 tifier (CID) and a 32-bit port number. The CID identifies the source
45 or destination, which is either a virtual machine or the host. The
46 port number differentiates between multiple services running on a sin‐
47 gle machine.
48 struct sockaddr_vm {
50 sa_family_t svm_family; /* Address family: AF_VSOCK */
51 unsigned short svm_reserved1;
52 unsigned int svm_port; /* Port # in host byte order */
53 unsigned int svm_cid; /* Address in host byte order */
54 unsigned char svm_zero[sizeof(struct sockaddr) -
55 sizeof(sa_family_t) -
56 sizeof(unsigned short) -
57 sizeof(unsigned int) -
58 sizeof(unsigned int)];
59 };
60 svm_family is always set to AF_VSOCK. svm_reserved1 is always set to
62 0. svm_port contains the port number in host byte order. The port
63 numbers below 1024 are called privileged ports. Only a process with
64 the CAP_NET_BIND_SERVICE capability may bind(2) to these port numbers.
65 svm_zero must be zero-filled.
66 There are several special addresses: VMADDR_CID_ANY (-1U) means any ad‐
68 dress for binding; VMADDR_CID_HYPERVISOR (0) is reserved for services
69 built into the hypervisor; VMADDR_CID_LOCAL (1) is the well-known ad‐
70 dress for local communication (loopback); VMADDR_CID_HOST [22m(2) is the
71 well-known address of the host.
72 The special constant VMADDR_PORT_ANY (-1U) means any port number for
74 binding.
75 Live migration
77 Sockets are affected by live migration of virtual machines. Connected
78 SOCK_STREAM sockets become disconnected when the virtual machine mi‐
79 grates to a new host. Applications must reconnect when this happens.
80 The local CID may change across live migration if the old CID is not
82 available on the new host. Bound sockets are automatically updated to
83 the new CID.
84 Ioctls
86 The following ioctls are available on the /dev/vsock device.
87 IOCTL_VM_SOCKETS_GET_LOCAL_CID
89 Get the CID of the local machine. The argument is a pointer to
90 an unsigned int.
91 ioctl(fd, IOCTL_VM_SOCKETS_GET_LOCAL_CID, &cid);
93 Consider using VMADDR_CID_ANY when binding instead of getting
95 the local CID with IOCTL_VM_SOCKETS_GET_LOCAL_CID.
96 Local communication
98 VMADDR_CID_LOCAL (1) directs packets to the same host that generated
99 them. This is useful for testing applications on a single host and for
100 debugging.
101 The local CID obtained with IOCTL_VM_SOCKETS_GET_LOCAL_CID can be used
103 for the same purpose, but it is preferable to use VMADDR_CID_LOCAL .
104
106 EACCES Unable to bind to a privileged port without the
107 CAP_NET_BIND_SERVICE capability.
108 EADDRINUSE
110 Unable to bind to a port that is already in use.
111 EADDRNOTAVAIL
113 Unable to find a free port for binding or unable to bind to a
114 nonlocal CID.
115 EINVAL Invalid parameters. This includes: attempting to bind a socket
117 that is already bound, providing an invalid struct sockaddr_vm,
118 and other input validation errors.
119 ENOPROTOOPT
121 Invalid socket option in setsockopt(2) or getsockopt(2).
122 ENOTCONN
124 Unable to perform operation on an unconnected socket.
125 EOPNOTSUPP
127 Operation not supported. This includes: the MSG_OOB flag that
128 is not implemented for the send(2) family of syscalls and
129 MSG_PEEK for the recv(2) family of syscalls.
130 EPROTONOSUPPORT
132 Invalid socket protocol number. The protocol should always be
133 0.
134 ESOCKTNOSUPPORT
136 Unsupported socket type in socket(2). Only SOCK_STREAM and
137 SOCK_DGRAM are valid.
138
140 Support for VMware (VMCI) has been available since Linux 3.9. KVM
141 (virtio) is supported since Linux 4.8. Hyper-V is supported since
142 Linux 4.14.
143 VMADDR_CID_LOCAL is supported since Linux 5.6. Local communication in
145 the guest and on the host is available since Linux 5.6. Previous ver‐
146 sions supported only local communication within a guest (not on the
147 host), and with only some transports (VMCI and virtio).
148
150 bind(2), connect(2), listen(2), recv(2), send(2), socket(2), capabili‐
151 ties(7)
152
154 This page is part of release 5.12 of the Linux man-pages project. A
155 description of the project, information about reporting bugs, and the
156 latest version of this page, can be found at
157 https://www.kernel.org/doc/man-pages/.
158Linux 2021-03-22 VSOCK(7)