1VSOCK(7)                   Linux Programmer's Manual                  VSOCK(7)
2
3
4

NAME

6       vsock - Linux VSOCK address family
7

SYNOPSIS

9       #include <sys/socket.h>
10       #include <linux/vm_sockets.h>
11
12       stream_socket = socket(AF_VSOCK, SOCK_STREAM, 0);
13       datagram_socket = socket(AF_VSOCK, SOCK_DGRAM, 0);
14

DESCRIPTION

16       The  VSOCK address family facilitates communication between virtual ma‐
17       chines and the host they are running on.  This address family  is  used
18       by  guest  agents  and  hypervisor  services that need a communications
19       channel that is independent of virtual machine network configuration.
20
21       Valid socket types are SOCK_STREAM and  SOCK_DGRAM.   SOCK_STREAM  pro‐
22       vides connection-oriented byte streams with guaranteed, in-order deliv‐
23       ery.  SOCK_DGRAM provides a connectionless datagram packet service with
24       best-effort  delivery  and best-effort ordering.  Availability of these
25       socket types is dependent on the underlying hypervisor.
26
27       A new socket is created with
28
29           socket(AF_VSOCK, socket_type, 0);
30
31       When a process wants to establish a  connection,  it  calls  connect(2)
32       with  a  given destination socket address.  The socket is automatically
33       bound to a free port if unbound.
34
35       A process can listen for incoming connections by  first  binding  to  a
36       socket address using bind(2) and then calling listen(2).
37
38       Data  is  transmitted  using the send(2) or write(2) families of system
39       calls and data is received using the recv(2)  or  read(2)  families  of
40       system calls.
41
42   Address format
43       A  socket address is defined as a combination of a 32-bit Context Iden‐
44       tifier (CID) and a 32-bit port number.  The CID identifies  the  source
45       or  destination,  which  is  either a virtual machine or the host.  The
46       port number differentiates between multiple services running on a  sin‐
47       gle machine.
48
49           struct sockaddr_vm {
50               sa_family_t    svm_family;     /* Address family: AF_VSOCK */
51               unsigned short svm_reserved1;
52               unsigned int   svm_port;       /* Port # in host byte order */
53               unsigned int   svm_cid;        /* Address in host byte order */
54               unsigned char  svm_zero[sizeof(struct sockaddr) -
55                                       sizeof(sa_family_t) -
56                                       sizeof(unsigned short) -
57                                       sizeof(unsigned int) -
58                                       sizeof(unsigned int)];
59           };
60
61       svm_family  is  always set to AF_VSOCK.  svm_reserved1 is always set to
62       0.  svm_port contains the port number in host  byte  order.   The  port
63       numbers  below  1024  are called privileged ports.  Only a process with
64       the CAP_NET_BIND_SERVICE capability may bind(2) to these port  numbers.
65       svm_zero must be zero-filled.
66
67       There are several special addresses: VMADDR_CID_ANY (-1U) means any ad‐
68       dress for binding; VMADDR_CID_HYPERVISOR (0) is reserved  for  services
69       built  into  the hypervisor; VMADDR_CID_LOCAL (1) is the well-known ad‐
70       dress for local communication (loopback); VMADDR_CID_HOST  (2)  is  the
71       well-known address of the host.
72
73       The  special  constant  VMADDR_PORT_ANY (-1U) means any port number for
74       binding.
75
76   Live migration
77       Sockets are affected by live migration of virtual machines.   Connected
78       SOCK_STREAM  sockets  become  disconnected when the virtual machine mi‐
79       grates to a new host.  Applications must reconnect when this happens.
80
81       The local CID may change across live migration if the old  CID  is  not
82       available  on the new host.  Bound sockets are automatically updated to
83       the new CID.
84
85   Ioctls
86       IOCTL_VM_SOCKETS_GET_LOCAL_CID
87              Get the CID of the local machine.  The argument is a pointer  to
88              an unsigned int.
89
90                  ioctl(socket, IOCTL_VM_SOCKETS_GET_LOCAL_CID, &cid);
91
92              Consider  using  VMADDR_CID_ANY  when binding instead of getting
93              the local CID with IOCTL_VM_SOCKETS_GET_LOCAL_CID.
94
95   Local communication
96       VMADDR_CID_LOCAL (1) directs packets to the same  host  that  generated
97       them.  This is useful for testing applications on a single host and for
98       debugging.
99
100       The local CID obtained with IOCTL_VM_SOCKETS_GET_LOCAL_CID can be  used
101       for the same purpose, but it is preferable to use VMADDR_CID_LOCAL .
102

ERRORS

104       EACCES Unable    to   bind   to   a   privileged   port   without   the
105              CAP_NET_BIND_SERVICE capability.
106
107       EADDRINUSE
108              Unable to bind to a port that is already in use.
109
110       EADDRNOTAVAIL
111              Unable to find a free port for binding or unable to  bind  to  a
112              nonlocal CID.
113
114       EINVAL Invalid  parameters.  This includes: attempting to bind a socket
115              that is already bound, providing an invalid struct  sockaddr_vm,
116              and other input validation errors.
117
118       ENOPROTOOPT
119              Invalid socket option in setsockopt(2) or getsockopt(2).
120
121       ENOTCONN
122              Unable to perform operation on an unconnected socket.
123
124       EOPNOTSUPP
125              Operation  not  supported.  This includes: the MSG_OOB flag that
126              is not implemented  for  the  send(2)  family  of  syscalls  and
127              MSG_PEEK for the recv(2) family of syscalls.
128
129       EPROTONOSUPPORT
130              Invalid  socket  protocol number.  The protocol should always be
131              0.
132
133       ESOCKTNOSUPPORT
134              Unsupported socket type  in  socket(2).   Only  SOCK_STREAM  and
135              SOCK_DGRAM are valid.
136

VERSIONS

138       Support  for  VMware  (VMCI)  has  been available since Linux 3.9.  KVM
139       (virtio) is supported since Linux  4.8.   Hyper-V  is  supported  since
140       Linux 4.14.
141
142       VMADDR_CID_LOCAL  is supported since Linux 5.6.  Local communication in
143       the guest and on the host is available since Linux 5.6.  Previous  ver‐
144       sions  supported  only  local  communication within a guest (not on the
145       host), and with only some transports (VMCI and virtio).
146

SEE ALSO

148       bind(2), connect(2), listen(2), recv(2), send(2), socket(2),  capabili‐
149       ties(7)
150

COLOPHON

152       This  page  is  part of release 5.10 of the Linux man-pages project.  A
153       description of the project, information about reporting bugs,  and  the
154       latest     version     of     this    page,    can    be    found    at
155       https://www.kernel.org/doc/man-pages/.
156
157
158
159Linux                             2020-02-09                          VSOCK(7)
Impressum