* [PATCH] vsock.7: document VSOCK socket address family
@ 2017-11-30 11:21 Stefan Hajnoczi
[not found] ` <20171130112153.13885-1-stefanha-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
0 siblings, 1 reply; 10+ messages in thread
From: Stefan Hajnoczi @ 2017-11-30 11:21 UTC (permalink / raw)
To: linux-man; +Cc: netdev, Dexuan Cui, Jorgen Hansen, Stefan Hajnoczi
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 <jhansen@vmware.com>
CC: Dexuan Cui <decui@microsoft.com>
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
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 <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
+.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)
--
2.14.3
^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: [PATCH] vsock.7: document VSOCK socket address family
[not found] ` <20171130112153.13885-1-stefanha-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
@ 2017-11-30 13:21 ` Jorgen S. Hansen
[not found] ` <33989114-7BC7-455A-BE36-9EEC989DBDF1-pghWNbHTmq7QT0dZR+AlfA@public.gmane.org>
2018-01-26 21:47 ` Michael Kerrisk (man-pages)
1 sibling, 1 reply; 10+ messages in thread
From: Jorgen S. Hansen @ 2017-11-30 13:21 UTC (permalink / raw)
To: Stefan Hajnoczi
Cc: linux-man-u79uwXL29TY76Z2rM5mHXA, netdev-u79uwXL29TY76Z2rM5mHXA,
Dexuan Cui
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset="utf-8", Size: 6702 bytes --]
> On Nov 30, 2017, at 12:21 PM, Stefan Hajnoczi <stefanha@redhat.com> wrote:
>
> 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 <jhansen@vmware.com>
> CC: Dexuan Cui <decui@microsoft.com>
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
> 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 <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
> +.B SOCK_DGRAM .
The space here results in a space between SOCK_DGRAM and the â.â in the formatted text. Is that intentional?
> +.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 .
Again the space before â."
> +.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
We use VMADDR_CID_HYPERVISOR for communicating with services in the hypervisor, so you could describe this as âan address reserved for services built into the 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 .
space before â.â
> +.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 ,
space before â,â
> +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
VMware (VMCI) for clarity.
> +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)
> --
> 2.14.3
>
Apart from the nits, this looks great.
Thanks,
Jorgen
N§²æìr¸yúèØb²X¬¶Ç§vØ^)Þº{.nÇ+·¥{±©âØ^nr¡ö¦zË\x1aëh¨èÚ&¢îý»\x05ËÛÔØï¦v¬Îf\x1dp)¹¹br ê+Ê+zf£¢·h§~Ûiÿûàz¹\x1e®w¥¢¸?¨èÚ&¢)ߢ^[f
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] vsock.7: document VSOCK socket address family
[not found] ` <33989114-7BC7-455A-BE36-9EEC989DBDF1-pghWNbHTmq7QT0dZR+AlfA@public.gmane.org>
@ 2017-12-01 13:09 ` Stefan Hajnoczi
[not found] ` <20171201130901.GA12803-lxVrvc10SDRcolVlb+j0YCZi+YwRKgec@public.gmane.org>
0 siblings, 1 reply; 10+ messages in thread
From: Stefan Hajnoczi @ 2017-12-01 13:09 UTC (permalink / raw)
To: Jorgen S. Hansen
Cc: linux-man-u79uwXL29TY76Z2rM5mHXA, netdev-u79uwXL29TY76Z2rM5mHXA,
Dexuan Cui
[-- Attachment #1: Type: text/plain, Size: 1207 bytes --]
On Thu, Nov 30, 2017 at 01:21:26PM +0000, Jorgen S. Hansen wrote:
> > On Nov 30, 2017, at 12:21 PM, Stefan Hajnoczi <stefanha-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
Thanks for the quick review!
I forgot to ask you: Is SOCK_DGRAM reliable and in-order over VMCI?
> > +.PP
> > +Valid socket types are
> > +.B SOCK_STREAM
> > +and
> > +.B SOCK_DGRAM .
>
> The space here results in a space between SOCK_DGRAM and the “.” in the formatted text. Is that intentional?
I haven't figured out the groff syntax to avoid the space :(. Any
ideas?
> > +.PP
> > +There are several special addresses:
> > +.B VMADDR_CID_ANY
> > +(-1U)
> > +means any address for binding;
> > +.B VMADDR_CID_HYPERVISOR
>
> We use VMADDR_CID_HYPERVISOR for communicating with services in the hypervisor, so you could describe this as “an address reserved for services built into the hypervisor”.
Will fix.
> > +.SH VERSIONS
> > +Support for VMware has been available since Linux 3.9. KVM (virtio) is
>
> VMware (VMCI) for clarity.
Will fix.
> Apart from the nits, this looks great.
Please let me know if there are any other topics that we should cover in
the man page.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 455 bytes --]
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] vsock.7: document VSOCK socket address family
[not found] ` <20171201130901.GA12803-lxVrvc10SDRcolVlb+j0YCZi+YwRKgec@public.gmane.org>
@ 2017-12-01 14:21 ` Jorgen S. Hansen
2017-12-01 14:57 ` G. Branden Robinson
1 sibling, 0 replies; 10+ messages in thread
From: Jorgen S. Hansen @ 2017-12-01 14:21 UTC (permalink / raw)
To: Stefan Hajnoczi
Cc: linux-man-u79uwXL29TY76Z2rM5mHXA, netdev-u79uwXL29TY76Z2rM5mHXA,
Dexuan Cui
> On Dec 1, 2017, at 2:09 PM, Stefan Hajnoczi <stefanha@redhat.com> wrote:
>
> On Thu, Nov 30, 2017 at 01:21:26PM +0000, Jorgen S. Hansen wrote:
>>> On Nov 30, 2017, at 12:21 PM, Stefan Hajnoczi <stefanha@redhat.com> wrote:
>
> Thanks for the quick review!
>
> I forgot to ask you: Is SOCK_DGRAM reliable and in-order over VMCI?
No, that isn’t guaranteed.
>
>>> +.PP
>>> +Valid socket types are
>>> +.B SOCK_STREAM
>>> +and
>>> +.B SOCK_DGRAM .
>>
>> The space here results in a space between SOCK_DGRAM and the “.” in the formatted text. Is that intentional?
>
> I haven't figured out the groff syntax to avoid the space :(. Any
> ideas?
Looks like man 7 unix has a few examples with bold and “,” - maybe look at the source for that.
>
>> Apart from the nits, this looks great.
>
> Please let me know if there are any other topics that we should cover in
> the man page.
Sure, I’ll get back to you soon, if I think of anything.
Thanks,
Jorgen
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] vsock.7: document VSOCK socket address family
[not found] ` <20171201130901.GA12803-lxVrvc10SDRcolVlb+j0YCZi+YwRKgec@public.gmane.org>
2017-12-01 14:21 ` Jorgen S. Hansen
@ 2017-12-01 14:57 ` G. Branden Robinson
[not found] ` <20171201145702.saqodo5qqh4ucbaq-Z0uaYDh/Ni4SozaZsD9aTtHuzzzSOjJt@public.gmane.org>
1 sibling, 1 reply; 10+ messages in thread
From: G. Branden Robinson @ 2017-12-01 14:57 UTC (permalink / raw)
To: Stefan Hajnoczi
Cc: Jorgen S. Hansen, linux-man-u79uwXL29TY76Z2rM5mHXA,
netdev-u79uwXL29TY76Z2rM5mHXA, Dexuan Cui
[-- Attachment #1: Type: text/plain, Size: 906 bytes --]
At 2017-12-01T13:09:01+0000, Stefan Hajnoczi wrote:
> On Thu, Nov 30, 2017 at 01:21:26PM +0000, Jorgen S. Hansen wrote:
> > > On Nov 30, 2017, at 12:21 PM, Stefan Hajnoczi <stefanha-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
>
> Thanks for the quick review!
>
> I forgot to ask you: Is SOCK_DGRAM reliable and in-order over VMCI?
>
> > > +.PP
> > > +Valid socket types are
> > > +.B SOCK_STREAM
> > > +and
> > > +.B SOCK_DGRAM .
> >
> > The space here results in a space between SOCK_DGRAM and the “.” in the formatted text. Is that intentional?
>
> I haven't figured out the groff syntax to avoid the space :(. Any
> ideas?
What you want is the .BR macro.
.BR SOCK_DGRAM .
The man macro package defines six "two-font" macros for switching
between roman, bold, and italic faces without intervening space.
See man(7) and groff_man(7).
--
Regards,
Branden
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] vsock.7: document VSOCK socket address family
[not found] ` <20171201145702.saqodo5qqh4ucbaq-Z0uaYDh/Ni4SozaZsD9aTtHuzzzSOjJt@public.gmane.org>
@ 2017-12-02 17:57 ` Stefan Hajnoczi
0 siblings, 0 replies; 10+ messages in thread
From: Stefan Hajnoczi @ 2017-12-02 17:57 UTC (permalink / raw)
To: G. Branden Robinson
Cc: Jorgen S. Hansen, linux-man-u79uwXL29TY76Z2rM5mHXA,
netdev-u79uwXL29TY76Z2rM5mHXA, Dexuan Cui
[-- Attachment #1: Type: text/plain, Size: 1039 bytes --]
On Fri, Dec 01, 2017 at 09:57:04AM -0500, G. Branden Robinson wrote:
> At 2017-12-01T13:09:01+0000, Stefan Hajnoczi wrote:
> > On Thu, Nov 30, 2017 at 01:21:26PM +0000, Jorgen S. Hansen wrote:
> > > > On Nov 30, 2017, at 12:21 PM, Stefan Hajnoczi <stefanha-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> >
> > Thanks for the quick review!
> >
> > I forgot to ask you: Is SOCK_DGRAM reliable and in-order over VMCI?
> >
> > > > +.PP
> > > > +Valid socket types are
> > > > +.B SOCK_STREAM
> > > > +and
> > > > +.B SOCK_DGRAM .
> > >
> > > The space here results in a space between SOCK_DGRAM and the “.” in the formatted text. Is that intentional?
> >
> > I haven't figured out the groff syntax to avoid the space :(. Any
> > ideas?
>
> What you want is the .BR macro.
>
> .BR SOCK_DGRAM .
>
> The man macro package defines six "two-font" macros for switching
> between roman, bold, and italic faces without intervening space.
>
> See man(7) and groff_man(7).
Excellent, thank you!
Stefan
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 455 bytes --]
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] vsock.7: document VSOCK socket address family
[not found] ` <20171130112153.13885-1-stefanha-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
2017-11-30 13:21 ` Jorgen S. Hansen
@ 2018-01-26 21:47 ` Michael Kerrisk (man-pages)
[not found] ` <CAKgNAkj=SvKSgg+hp3MXBpQF9PqJLGrEmiJuxJb3b-N=NfFYSQ-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
1 sibling, 1 reply; 10+ messages in thread
From: Michael Kerrisk (man-pages) @ 2018-01-26 21:47 UTC (permalink / raw)
To: Stefan Hajnoczi; +Cc: linux-man, netdev, Dexuan Cui, Jorgen Hansen
Stefan,
I've just now noted that your page came with no license. What license
do you want to use Please see
https://www.kernel.org/doc/man-pages/licenses.html
Thanks,
Michael
On 30 November 2017 at 12:21, Stefan Hajnoczi <stefanha-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> 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 <jhansen-pghWNbHTmq7QT0dZR+AlfA@public.gmane.org>
> CC: Dexuan Cui <decui-0li6OtcxBFHby3iVrkZq2A@public.gmane.org>
> Signed-off-by: Stefan Hajnoczi <stefanha-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> ---
> 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 <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
> +.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)
> --
> 2.14.3
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-man" in
> the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> More majordomo info at http://vger.kernel.org/majordomo-info.html
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] vsock.7: document VSOCK socket address family
[not found] ` <CAKgNAkj=SvKSgg+hp3MXBpQF9PqJLGrEmiJuxJb3b-N=NfFYSQ-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
@ 2018-01-30 21:31 ` Michael Kerrisk (man-pages)
2018-02-01 18:03 ` Stefan Hajnoczi
0 siblings, 1 reply; 10+ messages in thread
From: Michael Kerrisk (man-pages) @ 2018-01-30 21:31 UTC (permalink / raw)
To: Stefan Hajnoczi; +Cc: linux-man, netdev, Dexuan Cui, Jorgen Hansen
Hi Stefan,
Ping on the below please, since it either blocks the man-pages release
I'd currently like to make, or I must remove the vsock.7 page for this
release.
Thanks,
Michael
On 26 January 2018 at 22:47, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Stefan,
>
> I've just now noted that your page came with no license. What license
> do you want to use Please see
> https://www.kernel.org/doc/man-pages/licenses.html
>
> Thanks,
>
> Michael
>
>
> On 30 November 2017 at 12:21, Stefan Hajnoczi <stefanha-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
>> 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 <jhansen-pghWNbHTmq7QT0dZR+AlfA@public.gmane.org>
>> CC: Dexuan Cui <decui-0li6OtcxBFHby3iVrkZq2A@public.gmane.org>
>> Signed-off-by: Stefan Hajnoczi <stefanha-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>> ---
>> 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 <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
>> +.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)
>> --
>> 2.14.3
>>
>> --
>> To unsubscribe from this list: send the line "unsubscribe linux-man" in
>> the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
>> More majordomo info at http://vger.kernel.org/majordomo-info.html
>
>
>
> --
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Linux/UNIX System Programming Training: http://man7.org/training/
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] vsock.7: document VSOCK socket address family
2018-01-30 21:31 ` Michael Kerrisk (man-pages)
@ 2018-02-01 18:03 ` Stefan Hajnoczi
[not found] ` <20180201180349.GJ5578-lxVrvc10SDRcolVlb+j0YCZi+YwRKgec@public.gmane.org>
0 siblings, 1 reply; 10+ messages in thread
From: Stefan Hajnoczi @ 2018-02-01 18:03 UTC (permalink / raw)
To: Michael Kerrisk (man-pages); +Cc: linux-man, netdev, Dexuan Cui, Jorgen Hansen
[-- Attachment #1: Type: text/plain, Size: 321 bytes --]
On Tue, Jan 30, 2018 at 10:31:54PM +0100, Michael Kerrisk (man-pages) wrote:
> Hi Stefan,
>
> Ping on the below please, since it either blocks the man-pages release
> I'd currently like to make, or I must remove the vsock.7 page for this
> release.
Sorry for the delay. The verbatim license is fine.
Stefan
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 455 bytes --]
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] vsock.7: document VSOCK socket address family
[not found] ` <20180201180349.GJ5578-lxVrvc10SDRcolVlb+j0YCZi+YwRKgec@public.gmane.org>
@ 2018-02-01 21:24 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 10+ messages in thread
From: Michael Kerrisk (man-pages) @ 2018-02-01 21:24 UTC (permalink / raw)
To: Stefan Hajnoczi; +Cc: linux-man, netdev, Dexuan Cui, Jorgen Hansen
On 1 February 2018 at 19:03, Stefan Hajnoczi <stefanha-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> On Tue, Jan 30, 2018 at 10:31:54PM +0100, Michael Kerrisk (man-pages) wrote:
>> Hi Stefan,
>>
>> Ping on the below please, since it either blocks the man-pages release
>> I'd currently like to make, or I must remove the vsock.7 page for this
>> release.
>
> Sorry for the delay. The verbatim license is fine.
Thanks, Stefan!
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2018-02-01 21:24 UTC | newest]
Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-11-30 11:21 [PATCH] vsock.7: document VSOCK socket address family Stefan Hajnoczi
[not found] ` <20171130112153.13885-1-stefanha-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
2017-11-30 13:21 ` Jorgen S. Hansen
[not found] ` <33989114-7BC7-455A-BE36-9EEC989DBDF1-pghWNbHTmq7QT0dZR+AlfA@public.gmane.org>
2017-12-01 13:09 ` Stefan Hajnoczi
[not found] ` <20171201130901.GA12803-lxVrvc10SDRcolVlb+j0YCZi+YwRKgec@public.gmane.org>
2017-12-01 14:21 ` Jorgen S. Hansen
2017-12-01 14:57 ` G. Branden Robinson
[not found] ` <20171201145702.saqodo5qqh4ucbaq-Z0uaYDh/Ni4SozaZsD9aTtHuzzzSOjJt@public.gmane.org>
2017-12-02 17:57 ` Stefan Hajnoczi
2018-01-26 21:47 ` Michael Kerrisk (man-pages)
[not found] ` <CAKgNAkj=SvKSgg+hp3MXBpQF9PqJLGrEmiJuxJb3b-N=NfFYSQ-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
2018-01-30 21:31 ` Michael Kerrisk (man-pages)
2018-02-01 18:03 ` Stefan Hajnoczi
[not found] ` <20180201180349.GJ5578-lxVrvc10SDRcolVlb+j0YCZi+YwRKgec@public.gmane.org>
2018-02-01 21:24 ` Michael Kerrisk (man-pages)
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).