]>
Commit | Line | Data |
---|---|---|
93b96116 MK |
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 | .\" | |
6b621d05 | 25 | .TH VSOCK 7 2020-02-09 "Linux" "Linux Programmer's Manual" |
29598b2f SH |
26 | .SH NAME |
27 | vsock \- Linux VSOCK address family | |
28 | .SH SYNOPSIS | |
29 | .B #include <sys/socket.h> | |
30 | .br | |
31 | .B #include <linux/vm_sockets.h> | |
32 | .PP | |
33 | .IB stream_socket " = socket(AF_VSOCK, SOCK_STREAM, 0);" | |
34 | .br | |
35 | .IB datagram_socket " = socket(AF_VSOCK, SOCK_DGRAM, 0);" | |
36 | .SH DESCRIPTION | |
37 | The VSOCK address family facilitates communication between virtual machines and | |
4a70bb07 MK |
38 | the host they are running on. |
39 | This address family is used by guest agents and | |
29598b2f SH |
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 | |
4a70bb07 MK |
51 | best-effort ordering. |
52 | Availability of these socket types is dependent on the | |
29598b2f SH |
53 | underlying hypervisor. |
54 | .PP | |
55 | A new socket is created with | |
56 | .PP | |
24729221 MK |
57 | .in +4n |
58 | .EX | |
59 | socket(AF_VSOCK, socket_type, 0); | |
60 | .EE | |
61 | .in | |
29598b2f | 62 | .PP |
24729221 | 63 | When a process wants to establish a connection, it calls |
29598b2f | 64 | .BR connect (2) |
4a70bb07 MK |
65 | with a given destination socket address. |
66 | The socket is automatically bound to a free port if unbound. | |
29598b2f SH |
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 | |
ba294a0e | 74 | Data is transmitted using the |
29598b2f | 75 | .BR send (2) |
ba294a0e SH |
76 | or |
77 | .BR write (2) | |
78 | families of system calls and data is received using the | |
29598b2f | 79 | .BR recv (2) |
ba294a0e SH |
80 | or |
81 | .BR read (2) | |
82 | families of system calls. | |
29598b2f SH |
83 | .SS Address format |
84 | A socket address is defined as a combination of a 32-bit Context Identifier | |
4a70bb07 MK |
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. | |
29598b2f SH |
90 | .PP |
91 | .in +4n | |
92 | .EX | |
93 | struct sockaddr_vm { | |
24729221 MK |
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 */ | |
cf4e631c MK |
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)]; | |
29598b2f SH |
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 | |
24729221 | 113 | contains the port number in host byte order. |
29598b2f SH |
114 | The port numbers below 1024 are called |
115 | .IR "privileged ports" . | |
24729221 MK |
116 | Only a process with the |
117 | .B CAP_NET_BIND_SERVICE | |
29598b2f SH |
118 | capability may |
119 | .BR bind (2) | |
120 | to these port numbers. | |
552c1210 | 121 | .I svm_zero |
4475e3f0 | 122 | must be zero-filled. |
29598b2f SH |
123 | .PP |
124 | There are several special addresses: | |
125 | .B VMADDR_CID_ANY | |
24729221 | 126 | (\-1U) |
29598b2f SH |
127 | means any address for binding; |
128 | .B VMADDR_CID_HYPERVISOR | |
129 | (0) is reserved for services built into the hypervisor; | |
cab58dfe SG |
130 | .B VMADDR_CID_LOCAL |
131 | (1) is the well-known address for local communication (loopback); | |
29598b2f SH |
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 | |
24729221 | 138 | (\-1U) |
29598b2f SH |
139 | means any port number for binding. |
140 | .SS Live migration | |
4a70bb07 MK |
141 | Sockets are affected by live migration of virtual machines. |
142 | Connected | |
29598b2f SH |
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 | |
4a70bb07 MK |
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. | |
29598b2f SH |
150 | .SS Ioctls |
151 | .TP | |
152 | .B IOCTL_VM_SOCKETS_GET_LOCAL_CID | |
4a70bb07 | 153 | Get the CID of the local machine. |
24729221 MK |
154 | The argument is a pointer to an |
155 | .IR "unsigned int" . | |
29598b2f SH |
156 | .IP |
157 | .in +4n | |
158 | .EX | |
24729221 | 159 | ioctl(socket, IOCTL_VM_SOCKETS_GET_LOCAL_CID, &cid); |
29598b2f SH |
160 | .EE |
161 | .in | |
162 | .IP | |
163 | Consider using | |
164 | .B VMADDR_CID_ANY | |
165 | when binding instead of getting the local CID with | |
166 | .BR IOCTL_VM_SOCKETS_GET_LOCAL_CID . | |
cab58dfe SG |
167 | .SS Local communication |
168 | .B VMADDR_CID_LOCAL | |
9359ebce MK |
169 | (1) directs packets to the same host that generated them. |
170 | This is useful | |
cab58dfe SG |
171 | for testing applications on a single host and for debugging. |
172 | .PP | |
173 | The local CID obtained with | |
174 | .BR IOCTL_VM_SOCKETS_GET_LOCAL_CID | |
175 | can be used for the same purpose, but it is preferable to use | |
176 | .B VMADDR_CID_LOCAL . | |
29598b2f SH |
177 | .SH ERRORS |
178 | .TP | |
179 | .B EACCES | |
180 | Unable to bind to a privileged port without the | |
181 | .B CAP_NET_BIND_SERVICE | |
182 | capability. | |
183 | .TP | |
308a16d9 MK |
184 | .B EADDRINUSE |
185 | Unable to bind to a port that is already in use. | |
186 | .TP | |
187 | .B EADDRNOTAVAIL | |
188 | Unable to find a free port for binding or unable to bind to a nonlocal CID. | |
189 | .TP | |
29598b2f | 190 | .B EINVAL |
4a70bb07 MK |
191 | Invalid parameters. |
192 | This includes: | |
29598b2f | 193 | attempting to bind a socket that is already bound, providing an invalid struct |
24729221 | 194 | .IR sockaddr_vm , |
29598b2f SH |
195 | and other input validation errors. |
196 | .TP | |
308a16d9 MK |
197 | .B ENOPROTOOPT |
198 | Invalid socket option in | |
199 | .BR setsockopt (2) | |
200 | or | |
201 | .BR getsockopt (2). | |
202 | .TP | |
203 | .B ENOTCONN | |
204 | Unable to perform operation on an unconnected socket. | |
205 | .TP | |
29598b2f | 206 | .B EOPNOTSUPP |
4a70bb07 MK |
207 | Operation not supported. |
208 | This includes: | |
29598b2f SH |
209 | the |
210 | .B MSG_OOB | |
ba294a0e SH |
211 | flag that is not implemented for the |
212 | .BR send (2) | |
213 | family of syscalls and | |
29598b2f | 214 | .B MSG_PEEK |
ba294a0e SH |
215 | for the |
216 | .BR recv (2) | |
217 | family of syscalls. | |
29598b2f | 218 | .TP |
29598b2f | 219 | .B EPROTONOSUPPORT |
4a70bb07 | 220 | Invalid socket protocol number. |
24729221 | 221 | The protocol should always be 0. |
29598b2f SH |
222 | .TP |
223 | .B ESOCKTNOSUPPORT | |
224 | Unsupported socket type in | |
225 | .BR socket (2). | |
226 | Only | |
227 | .B SOCK_STREAM | |
228 | and | |
229 | .B SOCK_DGRAM | |
230 | are valid. | |
231 | .SH VERSIONS | |
4a70bb07 MK |
232 | Support for VMware (VMCI) has been available since Linux 3.9. |
233 | KVM (virtio) is supported since Linux 4.8. | |
24729221 | 234 | Hyper-V is supported since Linux 4.14. |
cab58dfe SG |
235 | .PP |
236 | VMADDR_CID_LOCAL is supported since Linux 5.6. | |
9359ebce | 237 | .\" commit ef343b35d46667668a099655fca4a5b2e43a5dfe |
cab58dfe | 238 | Local communication in the guest and on the host is available since Linux 5.6. |
0a8a31e8 MK |
239 | Previous versions supported only local communication within a guest |
240 | (not on the host), and with only some transports (VMCI and virtio). | |
29598b2f | 241 | .SH SEE ALSO |
29598b2f SH |
242 | .BR bind (2), |
243 | .BR connect (2), | |
244 | .BR listen (2), | |
29598b2f | 245 | .BR recv (2), |
308a16d9 MK |
246 | .BR send (2), |
247 | .BR socket (2), | |
29598b2f | 248 | .BR capabilities (7) |