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