| 1 |
.\" Copyright, the authors of the Linux man-pages project |
| 2 |
.\" |
| 3 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 4 |
.\" |
| 5 |
.TH vsock 7 2025-05-17 "Linux man-pages 6.18" |
| 6 |
.SH NAME |
| 7 |
vsock \- Linux VSOCK address family |
| 8 |
.SH SYNOPSIS |
| 9 |
.nf |
| 10 |
.B #include <sys/socket.h> |
| 11 |
.B #include <linux/vm_sockets.h> |
| 12 |
.P |
| 13 |
.IB stream_socket " = socket(AF_VSOCK, SOCK_STREAM, 0);" |
| 14 |
.IB datagram_socket " = socket(AF_VSOCK, SOCK_DGRAM, 0);" |
| 15 |
.fi |
| 16 |
.SH DESCRIPTION |
| 17 |
The VSOCK address family facilitates communication between virtual machines and |
| 18 |
the host they are running on. |
| 19 |
This address family is used by guest agents and |
| 20 |
hypervisor services that need a communications channel that is independent of |
| 21 |
virtual machine network configuration. |
| 22 |
.P |
| 23 |
Valid socket types are |
| 24 |
.B SOCK_STREAM |
| 25 |
and |
| 26 |
.BR SOCK_DGRAM . |
| 27 |
.B SOCK_STREAM |
| 28 |
provides connection-oriented byte streams with guaranteed, in-order delivery. |
| 29 |
.B SOCK_DGRAM |
| 30 |
provides a connectionless datagram packet service with best-effort delivery and |
| 31 |
best-effort ordering. |
| 32 |
Availability of these socket types is dependent on the |
| 33 |
underlying hypervisor. |
| 34 |
.P |
| 35 |
A new socket is created with |
| 36 |
.P |
| 37 |
.in +4n |
| 38 |
.EX |
| 39 |
socket(AF_VSOCK, socket_type, 0); |
| 40 |
.EE |
| 41 |
.in |
| 42 |
.P |
| 43 |
When a process wants to establish a connection, it calls |
| 44 |
.BR connect (2) |
| 45 |
with a given destination socket address. |
| 46 |
The socket is automatically bound to a free port if unbound. |
| 47 |
.P |
| 48 |
A process can listen for incoming connections by first binding to a socket |
| 49 |
address using |
| 50 |
.BR bind (2) |
| 51 |
and then calling |
| 52 |
.BR listen (2). |
| 53 |
.P |
| 54 |
Data is transmitted using the |
| 55 |
.BR send (2) |
| 56 |
or |
| 57 |
.BR write (2) |
| 58 |
families of system calls and data is received using the |
| 59 |
.BR recv (2) |
| 60 |
or |
| 61 |
.BR read (2) |
| 62 |
families of system calls. |
| 63 |
.SS Address format |
| 64 |
A socket address is defined as a combination of a 32-bit Context Identifier |
| 65 |
(CID) and a 32-bit port number. |
| 66 |
The CID identifies the source or destination, |
| 67 |
which is either a virtual machine or the host. |
| 68 |
The port number differentiates between multiple services running on |
| 69 |
a single machine. |
| 70 |
.P |
| 71 |
.in +4n |
| 72 |
.EX |
| 73 |
struct sockaddr_vm { |
| 74 |
sa_family_t svm_family; /* Address family: AF_VSOCK */ |
| 75 |
unsigned short svm_reserved1; |
| 76 |
unsigned int svm_port; /* Port # in host byte order */ |
| 77 |
unsigned int svm_cid; /* Address in host byte order */ |
| 78 |
unsigned char svm_zero[sizeof(struct sockaddr) \- |
| 79 |
sizeof(sa_family_t) \- |
| 80 |
sizeof(unsigned short) \- |
| 81 |
sizeof(unsigned int) \- |
| 82 |
sizeof(unsigned int)]; |
| 83 |
}; |
| 84 |
.EE |
| 85 |
.in |
| 86 |
.P |
| 87 |
.I svm_family |
| 88 |
is always set to |
| 89 |
.BR AF_VSOCK . |
| 90 |
.I svm_reserved1 |
| 91 |
is always set to 0. |
| 92 |
.I svm_port |
| 93 |
contains the port number in host byte order. |
| 94 |
The port numbers below 1024 are called |
| 95 |
.IR "privileged ports" . |
| 96 |
Only a process with the |
| 97 |
.B CAP_NET_BIND_SERVICE |
| 98 |
capability may |
| 99 |
.BR bind (2) |
| 100 |
to these port numbers. |
| 101 |
.I svm_zero |
| 102 |
must be zero-filled. |
| 103 |
.P |
| 104 |
There are several special addresses: |
| 105 |
.B VMADDR_CID_ANY |
| 106 |
(\-1U) |
| 107 |
means any address for binding; |
| 108 |
.B VMADDR_CID_HYPERVISOR |
| 109 |
(0) is reserved for services built into the hypervisor; |
| 110 |
.B VMADDR_CID_LOCAL |
| 111 |
(1) is the well-known address for local communication (loopback); |
| 112 |
.B VMADDR_CID_HOST |
| 113 |
(2) |
| 114 |
is the well-known address of the host. |
| 115 |
.P |
| 116 |
The special constant |
| 117 |
.B VMADDR_PORT_ANY |
| 118 |
(\-1U) |
| 119 |
means any port number for binding. |
| 120 |
.SS Live migration |
| 121 |
Sockets are affected by live migration of virtual machines. |
| 122 |
Connected |
| 123 |
.B SOCK_STREAM |
| 124 |
sockets become disconnected when the virtual machine migrates to a new host. |
| 125 |
Applications must reconnect when this happens. |
| 126 |
.P |
| 127 |
The local CID may change across live migration if the old CID is |
| 128 |
not available on the new host. |
| 129 |
Bound sockets are automatically updated to the new CID. |
| 130 |
.SS Ioctls |
| 131 |
The following ioctls are available on the |
| 132 |
.I /dev/vsock |
| 133 |
device. |
| 134 |
.TP |
| 135 |
.B IOCTL_VM_SOCKETS_GET_LOCAL_CID |
| 136 |
Get the CID of the local machine. |
| 137 |
The argument is a pointer to an |
| 138 |
.IR "unsigned int" . |
| 139 |
.IP |
| 140 |
.in +4n |
| 141 |
.EX |
| 142 |
ioctl(fd, IOCTL_VM_SOCKETS_GET_LOCAL_CID, &cid); |
| 143 |
.EE |
| 144 |
.in |
| 145 |
.IP |
| 146 |
Consider using |
| 147 |
.B VMADDR_CID_ANY |
| 148 |
when binding instead of getting the local CID with |
| 149 |
.BR IOCTL_VM_SOCKETS_GET_LOCAL_CID . |
| 150 |
.SS Local communication |
| 151 |
.B VMADDR_CID_LOCAL |
| 152 |
(1) directs packets to the same host that generated them. |
| 153 |
This is useful |
| 154 |
for testing applications on a single host and for debugging. |
| 155 |
.P |
| 156 |
The local CID obtained with |
| 157 |
.B IOCTL_VM_SOCKETS_GET_LOCAL_CID |
| 158 |
can be used for the same purpose, but it is preferable to use |
| 159 |
.BR VMADDR_CID_LOCAL . |
| 160 |
.SH ERRORS |
| 161 |
.TP |
| 162 |
.B EACCES |
| 163 |
Unable to bind to a privileged port without the |
| 164 |
.B CAP_NET_BIND_SERVICE |
| 165 |
capability. |
| 166 |
.TP |
| 167 |
.B EADDRINUSE |
| 168 |
Unable to bind to a port that is already in use. |
| 169 |
.TP |
| 170 |
.B EADDRNOTAVAIL |
| 171 |
Unable to find a free port for binding or unable to bind to a nonlocal CID. |
| 172 |
.TP |
| 173 |
.B EINVAL |
| 174 |
Invalid parameters. |
| 175 |
This includes: |
| 176 |
attempting to bind a socket that is already bound, providing an invalid struct |
| 177 |
.IR sockaddr_vm , |
| 178 |
and other input validation errors. |
| 179 |
.TP |
| 180 |
.B ENOPROTOOPT |
| 181 |
Invalid socket option in |
| 182 |
.BR setsockopt (2) |
| 183 |
or |
| 184 |
.BR getsockopt (2). |
| 185 |
.TP |
| 186 |
.B ENOTCONN |
| 187 |
Unable to perform operation on an unconnected socket. |
| 188 |
.TP |
| 189 |
.B EOPNOTSUPP |
| 190 |
Operation not supported. |
| 191 |
This includes: |
| 192 |
the |
| 193 |
.B MSG_OOB |
| 194 |
flag that is not implemented for the |
| 195 |
.BR send (2) |
| 196 |
family of syscalls and |
| 197 |
.B MSG_PEEK |
| 198 |
for the |
| 199 |
.BR recv (2) |
| 200 |
family of syscalls. |
| 201 |
.TP |
| 202 |
.B EPROTONOSUPPORT |
| 203 |
Invalid socket protocol number. |
| 204 |
The protocol should always be 0. |
| 205 |
.TP |
| 206 |
.B ESOCKTNOSUPPORT |
| 207 |
Unsupported socket type in |
| 208 |
.BR socket (2). |
| 209 |
Only |
| 210 |
.B SOCK_STREAM |
| 211 |
and |
| 212 |
.B SOCK_DGRAM |
| 213 |
are valid. |
| 214 |
.SH VERSIONS |
| 215 |
Support for VMware (VMCI) has been available since Linux 3.9. |
| 216 |
KVM (virtio) is supported since Linux 4.8. |
| 217 |
Hyper-V is supported since Linux 4.14. |
| 218 |
.P |
| 219 |
.B VMADDR_CID_LOCAL |
| 220 |
is supported since Linux 5.6. |
| 221 |
.\" commit ef343b35d46667668a099655fca4a5b2e43a5dfe |
| 222 |
Local communication in the guest and on the host is available since Linux 5.6. |
| 223 |
Previous versions supported only local communication within a guest |
| 224 |
(not on the host), and with only some transports (VMCI and virtio). |
| 225 |
.SH SEE ALSO |
| 226 |
.BR bind (2), |
| 227 |
.BR connect (2), |
| 228 |
.BR listen (2), |
| 229 |
.BR recv (2), |
| 230 |
.BR send (2), |
| 231 |
.BR socket (2), |
| 232 |
.BR capabilities (7) |