diff options
Diffstat (limited to 'man7/vsock.7')
| -rw-r--r-- | man7/vsock.7 | 232 |
1 files changed, 0 insertions, 232 deletions
diff --git a/man7/vsock.7 b/man7/vsock.7 deleted file mode 100644 index 3d679c0..0000000 --- a/man7/vsock.7 +++ /dev/null @@ -1,232 +0,0 @@ -.\" Copyright (C) 2018, Stefan Hajnoczi <stefanha@redhat.com> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.TH vsock 7 2024-02-25 "Linux man-pages 6.7" -.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) |