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.
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 */ unsigned char svm_zero[sizeof(struct sockaddr) − sizeof(sa_family_t) − sizeof(unsigned short) − sizeof(unsigned int) − sizeof(unsigned int)]; };
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. svm_zero
must be zero-filled.
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_LOCAL (1) is the well-known
address for local communication (loopback); 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.
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.
IOCTL_VM_SOCKETS_GET_LOCAL_CIDGet 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.
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.
The local CID obtained with IOCTL_VM_SOCKETS_GET_LOCAL_CID can be
used for the same purpose, but it is preferable to use
VMADDR_CID_LOCAL
.
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.
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 0.
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.
VMADDR_CID_LOCAL is supported since Linux 5.6. 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).
This page is part of release 5.11 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/.
|
Copyright (C) 2018, Stefan Hajnoczi <stefanharedhat.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 |