man7/vsock.7

   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 2020-02-09 "Linux" "Linux Programmer's Manual"
  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
  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 .TP
 152 .B IOCTL_VM_SOCKETS_GET_LOCAL_CID
 153 Get the CID of the local machine.
 154 The argument is a pointer to an
 155 .IR "unsigned int" .
 156 .IP
 157 .in +4n
 158 .EX
 159 ioctl(socket, IOCTL_VM_SOCKETS_GET_LOCAL_CID, &cid);
 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 .
 167 .SS Local communication
 168 .B VMADDR_CID_LOCAL
 169 (1) directs packets to the same host that generated them.
 170 This is useful
 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 .
 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
 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
 190 .B EINVAL
 191 Invalid parameters.
 192 This includes:
 193 attempting to bind a socket that is already bound, providing an invalid struct
 194 .IR sockaddr_vm ,
 195 and other input validation errors.
 196 .TP
 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
 206 .B EOPNOTSUPP
 207 Operation not supported.
 208 This includes:
 209 the
 210 .B MSG_OOB
 211 flag that is not implemented for the
 212 .BR send (2)
 213 family of syscalls and
 214 .B MSG_PEEK
 215 for the
 216 .BR recv (2)
 217 family of syscalls.
 218 .TP
 219 .B EPROTONOSUPPORT
 220 Invalid socket protocol number.
 221 The protocol should always be 0.
 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
 232 Support for VMware (VMCI) has been available since Linux 3.9.
 233 KVM (virtio) is supported since Linux 4.8.
 234 Hyper-V is supported since Linux 4.14.
 235 .PP
 236 VMADDR_CID_LOCAL is supported since Linux 5.6.
 237 .\" commit ef343b35d46667668a099655fca4a5b2e43a5dfe
 238 Local communication in the guest and on the host is available since Linux 5.6.
 239 Previous versions supported only local communication within a guest
 240 (not on the host), and with only some transports (VMCI and virtio).
 241 .SH SEE ALSO
 242 .BR bind (2),
 243 .BR connect (2),
 244 .BR listen (2),
 245 .BR recv (2),
 246 .BR send (2),
 247 .BR socket (2),
 248 .BR capabilities (7)