focal (7) vsock.7.gz

NAME

       vsock - Linux VSOCK address family

SYNOPSIS

       #include <sys/socket.h>
       #include <linux/vm_sockets.h>

       stream_socket = socket(AF_VSOCK, SOCK_STREAM, 0);
       datagram_socket = socket(AF_VSOCK, SOCK_DGRAM, 0);

DESCRIPTION

       The VSOCK address family facilitates communication between virtual machines and the host they are running
       on.  This address family is used by guest agents and  hypervisor  services  that  need  a  communications
       channel that is independent of virtual machine network configuration.

       Valid socket types are SOCK_STREAM and SOCK_DGRAM.  SOCK_STREAM provides connection-oriented byte streams
       with guaranteed, in-order delivery.  SOCK_DGRAM provides a connectionless datagram  packet  service  with
       best-effort  delivery  and  best-effort ordering.  Availability of these socket types is dependent on the
       underlying hypervisor.

       A new socket is created with

           socket(AF_VSOCK, socket_type, 0);

       When a process wants to establish a connection, it calls  connect(2)  with  a  given  destination  socket
       address.  The socket is automatically bound to a free port if unbound.

       A process can listen for incoming connections by first binding to a socket address using bind(2) and then
       calling listen(2).

       Data is transmitted using the send(2) or write(2) families of system calls and data is received using the
       recv(2) or read(2) families of system calls.

   Address format
       A  socket  address  is  defined  as  a combination of a 32-bit Context Identifier (CID) and a 32-bit port
       number.  The CID identifies the source or destination, which is either a virtual  machine  or  the  host.
       The port number differentiates between multiple services running on a single machine.

           struct sockaddr_vm {
               sa_family_t    svm_family;     /* Address family: AF_VSOCK */
               unsigned short svm_reserved1;
               unsigned int   svm_port;       /* Port # in host byte order */
               unsigned int   svm_cid;        /* Address in host byte order */
               unsigned char  svm_zero[sizeof(struct sockaddr) -
                                       sizeof(sa_family_t) -
                                       sizeof(unsigned short) -
                                       sizeof(unsigned int) -
                                       sizeof(unsigned int)];
           };

       svm_family  is  always  set  to  AF_VSOCK.  svm_reserved1 is always set to 0.  svm_port contains the port
       number in host byte order.  The port numbers below 1024 are called privileged ports.  Only a process with
       the CAP_NET_BIND_SERVICE capability may bind(2) to these port numbers.  svm_zero must be zero-filled.

       There   are   several   special   addresses:   VMADDR_CID_ANY   (-1U)  means  any  address  for  binding;
       VMADDR_CID_HYPERVISOR (0) is reserved for services built into  the  hypervisor;  VMADDR_CID_RESERVED  (1)
       must not be used; VMADDR_CID_HOST (2) is the well-known address of the host.

       The special constant VMADDR_PORT_ANY (-1U) means any port number for binding.

   Live migration
       Sockets  are  affected  by  live  migration  of  virtual  machines.  Connected SOCK_STREAM sockets become
       disconnected when the virtual machine migrates to a new host.   Applications  must  reconnect  when  this
       happens.

       The  local  CID  may change across live migration if the old CID is not available on the new host.  Bound
       sockets are automatically updated to the new CID.

   Ioctls
       IOCTL_VM_SOCKETS_GET_LOCAL_CID
              Get the CID of the local machine.  The argument is a pointer to an unsigned int.

                  ioctl(socket, IOCTL_VM_SOCKETS_GET_LOCAL_CID, &cid);

              Consider  using  VMADDR_CID_ANY  when  binding   instead   of   getting   the   local   CID   with
              IOCTL_VM_SOCKETS_GET_LOCAL_CID.

ERRORS

       EACCES Unable to bind to a privileged port without the CAP_NET_BIND_SERVICE capability.

       EADDRINUSE
              Unable to bind to a port that is already in use.

       EADDRNOTAVAIL
              Unable to find a free port for binding or unable to bind to a nonlocal CID.

       EINVAL Invalid  parameters.   This includes: attempting to bind a socket that is already bound, providing
              an invalid struct sockaddr_vm, and other input validation errors.

       ENOPROTOOPT
              Invalid socket option in setsockopt(2) or getsockopt(2).

       ENOTCONN
              Unable to perform operation on an unconnected socket.

       EOPNOTSUPP
              Operation not supported.  This includes: the MSG_OOB flag that is not implemented for the  send(2)
              family of syscalls and MSG_PEEK for the recv(2) family of syscalls.

       EPROTONOSUPPORT
              Invalid socket protocol number.  The protocol should always be 0.

       ESOCKTNOSUPPORT
              Unsupported socket type in socket(2).  Only SOCK_STREAM and SOCK_DGRAM are valid.

VERSIONS

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

SEE ALSO

       bind(2), connect(2), listen(2), recv(2), send(2), socket(2), capabilities(7)

COLOPHON

       This page is part of release 5.05 of  the  Linux  man-pages  project.   A  description  of  the  project,
       information   about   reporting   bugs,   and   the  latest  version  of  this  page,  can  be  found  at
       https://www.kernel.org/doc/man-pages/.