Debian Codegraph @

upstream/debian-unstable/man7/vsock.7

raw
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)