From patchwork Thu Nov 30 11:21:53 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stefan Hajnoczi X-Patchwork-Id: 842961 X-Patchwork-Delegate: davem@davemloft.net Return-Path: X-Original-To: patchwork-incoming@ozlabs.org Delivered-To: patchwork-incoming@ozlabs.org Authentication-Results: ozlabs.org; spf=none (mailfrom) smtp.mailfrom=vger.kernel.org (client-ip=209.132.180.67; helo=vger.kernel.org; envelope-from=netdev-owner@vger.kernel.org; receiver=) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by ozlabs.org (Postfix) with ESMTP id 3ynZjz64wMz9t2f for ; Thu, 30 Nov 2017 22:21:59 +1100 (AEDT) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752415AbdK3LV5 (ORCPT ); Thu, 30 Nov 2017 06:21:57 -0500 Received: from mx1.redhat.com ([209.132.183.28]:53692 "EHLO mx1.redhat.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752365AbdK3LV4 (ORCPT ); Thu, 30 Nov 2017 06:21:56 -0500 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 183B968698; Thu, 30 Nov 2017 11:21:56 +0000 (UTC) Received: from localhost (ovpn-117-230.ams2.redhat.com [10.36.117.230]) by smtp.corp.redhat.com (Postfix) with ESMTP id 973D4620D8; Thu, 30 Nov 2017 11:21:54 +0000 (UTC) From: Stefan Hajnoczi To: linux-man@vger.kernel.org Cc: netdev@vger.kernel.org, Dexuan Cui , Jorgen Hansen , Stefan Hajnoczi Subject: [PATCH] vsock.7: document VSOCK socket address family Date: Thu, 30 Nov 2017 11:21:53 +0000 Message-Id: <20171130112153.13885-1-stefanha@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.27]); Thu, 30 Nov 2017 11:21:56 +0000 (UTC) Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org The AF_VSOCK address family has been available since Linux 3.9 without a corresponding man page. This patch adds vsock.7 and describes its use along the same lines as existing ip.7, unix.7, and netlink.7 man pages. CC: Jorgen Hansen CC: Dexuan Cui Signed-off-by: Stefan Hajnoczi --- man7/vsock.7 | 175 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 man7/vsock.7 diff --git a/man7/vsock.7 b/man7/vsock.7 new file mode 100644 index 000000000..48c6c2e1e --- /dev/null +++ b/man7/vsock.7 @@ -0,0 +1,175 @@ +.TH VSOCK 7 2017-11-30 "Linux" "Linux Programmer's Manual" +.SH NAME +vsock \- Linux VSOCK address family +.SH SYNOPSIS +.B #include +.br +.B #include +.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 +.B SOCK_DGRAM . +.B SOCK_STREAM +provides connection-oriented byte streams with guaranteed, in-order delivery. +.B SOCK_DGRAM +provides a connectionless datagram packet service. Availability of these +socket types is dependent on the underlying hypervisor. +.PP +A new socket is created with +.PP + socket(AF_VSOCK, socket_type, 0); +.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 transferred using the usual +.BR send (2) +and +.BR recv (2) +family of socket 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 native byte order */ + unsigned int svm_cid; /* address in native byte order */ +}; +.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 in native byte order. +The port numbers below 1024 are called +.IR "privileged ports" . +Only a process with +.B CAP_NET_BIND_SERVER +capability may +.BR bind (2) +to these port numbers. +.PP +There are several special addresses: +.B VMADDR_CID_ANY +(-1U) +means any address for binding; +.B VMADDR_CID_HYPERVISOR +(0) and +.B VMADDR_CID_RESERVED +(1) are unused addresses; +.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 unsigned int. +.IP +.in +4n +.EX +.IB error " = 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 +.B 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 EINVAL +Invalid parameters. This includes: +attempting to bind a socket that is already bound, providing an invalid struct +.B sockaddr_vm , +and other input validation errors. +.TP +.B EOPNOTSUPP +Operation not supported. This includes: +the +.B MSG_OOB +flag that is not implemented for +.B sendmsg (2) +and +.B MSG_PEEK +for +.B recvmsg (2). +.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 non-local CID. +.TP +.B ENOTCONN +Unable to perform operation on an unconnected socket. +.TP +.B ENOPROTOOPT +Invalid socket option in +.B setsockopt (2) +or +.B getsockopt (2). +.TP +.B EPROTONOSUPPORT +Invalid socket protocol number. Protocol should always be 0. +.TP +.B ESOCKTNOSUPPORT +Unsupported socket type in +.B socket (2). +Only +.B SOCK_STREAM +and +.B SOCK_DGRAM +are valid. +.SH VERSIONS +Support for VMware has been available since Linux 3.9. KVM (virtio) is +supported since Linux 4.8. Hyper-V is supported since 4.14. +.SH SEE ALSO +.BR socket (2), +.BR bind (2), +.BR connect (2), +.BR listen (2), +.BR send (2), +.BR recv (2), +.BR capabilities (7)