path: root/man/man7/vsock.7

.\" Copyright (C) 2018, Stefan Hajnoczi <stefanha@redhat.com>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH vsock 7 (date) "Linux man-pages (unreleased)"
.SH NAME
vsock \- Linux VSOCK address family
.SH SYNOPSIS
.nf
.B #include <sys/socket.h>
.B #include <linux/vm_sockets.h>
.P
.IB stream_socket " = socket(AF_VSOCK, SOCK_STREAM, 0);"
.IB datagram_socket " = socket(AF_VSOCK, SOCK_DGRAM, 0);"
.fi
.SH 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.
.P
Valid socket types are
.B SOCK_STREAM
and
.BR SOCK_DGRAM .
.B SOCK_STREAM
provides connection-oriented byte streams with guaranteed, in-order delivery.
.B 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.
.P
A new socket is created with
.P
.in +4n
.EX
socket(AF_VSOCK, socket_type, 0);
.EE
.in
.P
When a process wants to establish a connection, it calls
.BR connect (2)
with a given destination socket address.
The socket is automatically bound to a free port if unbound.
.P
A process can listen for incoming connections by first binding to a socket
address using
.BR bind (2)
and then calling
.BR listen (2).
.P
Data is transmitted using the
.BR send (2)
or
.BR write (2)
families of system calls and data is received using the
.BR recv (2)
or
.BR read (2)
families of system calls.
.SS 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.
.P
.in +4n
.EX
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)];
};
.EE
.in
.P
.I svm_family
is always set to
.BR AF_VSOCK .
.I svm_reserved1
is always set to 0.
.I svm_port
contains the port number in host byte order.
The port numbers below 1024 are called
.IR "privileged ports" .
Only a process with the
.B CAP_NET_BIND_SERVICE
capability may
.BR bind (2)
to these port numbers.
.I svm_zero
must be zero-filled.
.P
There are several special addresses:
.B VMADDR_CID_ANY
(\-1U)
means any address for binding;
.B VMADDR_CID_HYPERVISOR
(0) is reserved for services built into the hypervisor;
.B VMADDR_CID_LOCAL
(1) is the well-known address for local communication (loopback);
.B VMADDR_CID_HOST
(2)
is the well-known address of the host.
.P
The special constant
.B VMADDR_PORT_ANY
(\-1U)
means any port number for binding.
.SS Live migration
Sockets are affected by live migration of virtual machines.
Connected
.B SOCK_STREAM
sockets become disconnected when the virtual machine migrates to a new host.
Applications must reconnect when this happens.
.P
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.
.SS Ioctls
The following ioctls are available on the
.I /dev/vsock
device.
.TP
.B IOCTL_VM_SOCKETS_GET_LOCAL_CID
Get the CID of the local machine.
The argument is a pointer to an
.IR "unsigned int" .
.IP
.in +4n
.EX
ioctl(fd, IOCTL_VM_SOCKETS_GET_LOCAL_CID, &cid);
.EE
.in
.IP
Consider using
.B VMADDR_CID_ANY
when binding instead of getting the local CID with
.BR IOCTL_VM_SOCKETS_GET_LOCAL_CID .
.SS Local communication
.B VMADDR_CID_LOCAL
(1) directs packets to the same host that generated them.
This is useful
for testing applications on a single host and for debugging.
.P
The local CID obtained with
.B IOCTL_VM_SOCKETS_GET_LOCAL_CID
can be used for the same purpose, but it is preferable to use
.BR VMADDR_CID_LOCAL .
.SH ERRORS
.TP
.B EACCES
Unable to bind to a privileged port without the
.B CAP_NET_BIND_SERVICE
capability.
.TP
.B EADDRINUSE
Unable to bind to a port that is already in use.
.TP
.B EADDRNOTAVAIL
Unable to find a free port for binding or unable to bind to a nonlocal CID.
.TP
.B EINVAL
Invalid parameters.
This includes:
attempting to bind a socket that is already bound, providing an invalid struct
.IR sockaddr_vm ,
and other input validation errors.
.TP
.B ENOPROTOOPT
Invalid socket option in
.BR setsockopt (2)
or
.BR getsockopt (2).
.TP
.B ENOTCONN
Unable to perform operation on an unconnected socket.
.TP
.B EOPNOTSUPP
Operation not supported.
This includes:
the
.B MSG_OOB
flag that is not implemented for the
.BR send (2)
family of syscalls and
.B MSG_PEEK
for the
.BR recv (2)
family of syscalls.
.TP
.B EPROTONOSUPPORT
Invalid socket protocol number.
The protocol should always be 0.
.TP
.B ESOCKTNOSUPPORT
Unsupported socket type in
.BR socket (2).
Only
.B SOCK_STREAM
and
.B SOCK_DGRAM
are valid.
.SH 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.
.P
.B VMADDR_CID_LOCAL
is supported since Linux 5.6.
.\" commit ef343b35d46667668a099655fca4a5b2e43a5dfe
Local communication in the guest and on the host is available since Linux 5.6.
Previous versions supported only local communication within a guest
(not on the host), and with only some transports (VMCI and virtio).
.SH SEE ALSO
.BR bind (2),
.BR connect (2),
.BR listen (2),
.BR recv (2),
.BR send (2),
.BR socket (2),
.BR capabilities (7)