1 .\" Copyright (C) 2018, Stefan Hajnoczi <stefanha@redhat.com>
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.
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.
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
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
25 .TH VSOCK 7 2017-11-30 "Linux" "Linux Programmer's Manual"
27 vsock \- Linux VSOCK address family
29 .B #include <sys/socket.h>
31 .B #include <linux/vm_sockets.h>
33 .IB stream_socket " = socket(AF_VSOCK, SOCK_STREAM, 0);"
35 .IB datagram_socket " = socket(AF_VSOCK, SOCK_DGRAM, 0);"
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.
43 Valid socket types are
48 provides connection-oriented byte streams with guaranteed, in-order delivery.
50 provides a connectionless datagram packet service with best-effort delivery and
52 Availability of these socket types is dependent on the
53 underlying hypervisor.
55 A new socket is created with
59 socket(AF_VSOCK, socket_type, 0);
63 When a process wants to establish a connection, it calls
65 with a given destination socket address.
66 The socket is automatically bound to a free port if unbound.
68 A process can listen for incoming connections by first binding to a socket
74 Data is transmitted using the
78 families of system calls and data is received using the
82 families of system calls.
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
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 */
108 contains the port number in host byte order.
109 The port numbers below 1024 are called
110 .IR "privileged ports" .
111 Only a process with the
112 .B CAP_NET_BIND_SERVICE
115 to these port numbers.
117 There are several special addresses:
120 means any address for binding;
121 .B VMADDR_CID_HYPERVISOR
122 (0) is reserved for services built into the hypervisor;
123 .B VMADDR_CID_RESERVED
124 (1) must not be used;
127 is the well-known address of the host.
132 means any port number for binding.
134 Sockets are affected by live migration of virtual machines.
137 sockets become disconnected when the virtual machine migrates to a new host.
138 Applications must reconnect when this happens.
140 The local CID may change across live migration if the old CID is
141 not available on the new host.
142 Bound sockets are automatically updated to the new CID.
145 .B IOCTL_VM_SOCKETS_GET_LOCAL_CID
146 Get the CID of the local machine.
147 The argument is a pointer to an
152 ioctl(socket, IOCTL_VM_SOCKETS_GET_LOCAL_CID, &cid);
158 when binding instead of getting the local CID with
159 .BR IOCTL_VM_SOCKETS_GET_LOCAL_CID .
163 Unable to bind to a privileged port without the
164 .B CAP_NET_BIND_SERVICE
168 Unable to bind to a port that is already in use.
171 Unable to find a free port for binding or unable to bind to a nonlocal CID.
176 attempting to bind a socket that is already bound, providing an invalid struct
178 and other input validation errors.
181 Invalid socket option in
187 Unable to perform operation on an unconnected socket.
190 Operation not supported.
194 flag that is not implemented for the
196 family of syscalls and
203 Invalid socket protocol number.
204 The protocol should always be 0.
207 Unsupported socket type in
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.