|
NAME | SYNOPSIS | DESCRIPTION | ERRORS | VERSIONS | SEE ALSO | COLOPHON |
|
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
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 */
};
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 num‐
bers.
There are several special addresses: VMADDR_CID_ANY (-1U) means any
address for binding; VMADDR_CID_HYPERVISOR (0) is reserved for ser‐
vices 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. Con‐
nected 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.
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.
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),
capabilities(7)
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
https://www.kernel.org/doc/man-pages/.
Linux 2017-11-30 VSOCK(7)
Copyright and license for this manual page
|
HTML rendering created 2018-02-02 by Michael Kerrisk, author of The Linux Programming Interface, maintainer of the Linux man-pages project. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH.
|
|