diff options
Diffstat (limited to 'man/man7/vsock.7')
| -rw-r--r-- | man/man7/vsock.7 | 232 |
1 files changed, 232 insertions, 0 deletions
diff --git a/man/man7/vsock.7 b/man/man7/vsock.7 new file mode 100644 index 000000000..fb30781e0 --- /dev/null +++ b/man/man7/vsock.7 @@ -0,0 +1,232 @@ +.\" 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) |