vsock(7)

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
17       machines 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           };
55
56       svm_family  is  always set to AF_VSOCK.  svm_reserved1 is always set to
57       0.  svm_port contains the port number in host  byte  order.   The  port
58       numbers  below  1024  are called privileged ports.  Only a process with
59       the CAP_NET_BIND_SERVICE capability may bind(2) to these port numbers.
60
61       There are several special addresses:  VMADDR_CID_ANY  (-1U)  means  any
62       address for binding; VMADDR_CID_HYPERVISOR (0) is reserved for services
63       built into the hypervisor; VMADDR_CID_RESERVED (1) must  not  be  used;
64       VMADDR_CID_HOST (2) is the well-known address of the host.
65
66       The  special  constant  VMADDR_PORT_ANY (-1U) means any port number for
67       binding.
68
69   Live migration
70       Sockets are affected by live migration of virtual machines.   Connected
71       SOCK_STREAM  sockets  become  disconnected  when  the  virtual  machine
72       migrates to a new host.  Applications must reconnect when this happens.
73
74       The local CID may change across live migration if the old  CID  is  not
75       available  on the new host.  Bound sockets are automatically updated to
76       the new CID.
77
78   Ioctls
79       IOCTL_VM_SOCKETS_GET_LOCAL_CID
80              Get the CID of the local machine.  The argument is a pointer  to
81              an unsigned int.
82
83                  ioctl(socket, IOCTL_VM_SOCKETS_GET_LOCAL_CID, &cid);
84
85              Consider  using  VMADDR_CID_ANY  when binding instead of getting
86              the local CID with IOCTL_VM_SOCKETS_GET_LOCAL_CID.
87

ERRORS

89       EACCES Unable   to   bind   to   a   privileged   port   without    the
90              CAP_NET_BIND_SERVICE capability.
91
92       EADDRINUSE
93              Unable to bind to a port that is already in use.
94
95       EADDRNOTAVAIL
96              Unable  to  find  a free port for binding or unable to bind to a
97              nonlocal CID.
98
99       EINVAL Invalid parameters.  This includes: attempting to bind a  socket
100              that  is already bound, providing an invalid struct sockaddr_vm,
101              and other input validation errors.
102
103       ENOPROTOOPT
104              Invalid socket option in setsockopt(2) or getsockopt(2).
105
106       ENOTCONN
107              Unable to perform operation on an unconnected socket.
108
109       EOPNOTSUPP
110              Operation not supported.  This includes: the MSG_OOB  flag  that
111              is  not  implemented  for  the  send(2)  family  of syscalls and
112              MSG_PEEK for the recv(2) family of syscalls.
113
114       EPROTONOSUPPORT
115              Invalid socket protocol number.  The protocol should  always  be
116              0.
117
118       ESOCKTNOSUPPORT
119              Unsupported  socket  type  in  socket(2).   Only SOCK_STREAM and
120              SOCK_DGRAM are valid.
121

VERSIONS

123       Support for VMware (VMCI) has been  available  since  Linux  3.9.   KVM
124       (virtio)  is  supported  since  Linux  4.8.  Hyper-V is supported since
125       Linux 4.14.
126

COLOPHON

132       This  page  is  part of release 4.15 of the Linux man-pages project.  A
133       description of the project, information about reporting bugs,  and  the
134       latest     version     of     this    page,    can    be    found    at
135       https://www.kernel.org/doc/man-pages/.
136
137
138
139Linux                             2017-11-30                          VSOCK(7)

NAME

SYNOPSIS

DESCRIPTION

ERRORS

VERSIONS

SEE ALSO

COLOPHON