mirror of https://github.com/mkerrisk/man-pages
249 lines
6.8 KiB
Groff
249 lines
6.8 KiB
Groff
.\" Copyright (C) 2018, Stefan Hajnoczi <stefanha@redhat.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.TH VSOCK 7 2020-02-09 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
vsock \- Linux VSOCK address family
|
|
.SH SYNOPSIS
|
|
.B #include <sys/socket.h>
|
|
.br
|
|
.B #include <linux/vm_sockets.h>
|
|
.PP
|
|
.IB stream_socket " = socket(AF_VSOCK, SOCK_STREAM, 0);"
|
|
.br
|
|
.IB datagram_socket " = socket(AF_VSOCK, SOCK_DGRAM, 0);"
|
|
.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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
A new socket is created with
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
socket(AF_VSOCK, socket_type, 0);
|
|
.EE
|
|
.in
|
|
.PP
|
|
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.
|
|
.PP
|
|
A process can listen for incoming connections by first binding to a socket
|
|
address using
|
|
.BR bind (2)
|
|
and then calling
|
|
.BR listen (2).
|
|
.PP
|
|
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.
|
|
.PP
|
|
.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
|
|
.PP
|
|
.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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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
|
|
.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(socket, 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.
|
|
.PP
|
|
The local CID obtained with
|
|
.BR IOCTL_VM_SOCKETS_GET_LOCAL_CID
|
|
can be used for the same purpose, but it is preferable to use
|
|
.B 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.
|
|
.PP
|
|
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)
|