GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools


man:vsock

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

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  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
     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), capabili-
     ties(7)

COLOPHON

     This page is part of release 4.16 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/.

Linux 2017-11-30 VSOCK(7)

/data/webs/external/dokuwiki/data/pages/man/vsock.txt · Last modified: 2019/05/17 09:47 by 127.0.0.1

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki