| .\" 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 2017-11-30 "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_RESERVED |
| (1) must not be used; |
| .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 . |
| .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. |
| .SH SEE ALSO |
| .BR bind (2), |
| .BR connect (2), |
| .BR listen (2), |
| .BR recv (2), |
| .BR send (2), |
| .BR socket (2), |
| .BR capabilities (7) |