VSOCK(7)                   Linux Programmer's Manual                  VSOCK(7)

       vsock - Linux VSOCK address family

       #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);

       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  pro-
       vides connection-oriented byte streams with guaranteed, in-order deliv-
       ery.  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 Iden-
       tifier (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  sin-
       gle 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 */

       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.

       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

   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.

              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.

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

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

              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.

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

              Unable to perform operation on an unconnected socket.

              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.

              Invalid socket protocol number.  The protocol should  always  be

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

       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.

       bind(2), connect(2), listen(2), recv(2), send(2), socket(2),  capabili-

       This  page  is  part of release 4.15 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

Linux                             2017-11-30                          VSOCK(7)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2022 Hurricane Electric. All Rights Reserved.